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Notices 


Any reference to an IBM licensed program in this publication is not intended to state 
or imply that only IBM’s licensed program may be used. Any functionally equivalent 
product, program, or service that does not infringe any of IBM’s intellectual property 
rights may be used instead of the IBM product, program, or service. Evaluation and 
verification of operation in conjunction with other products, except those expressly 
designated by IBM, is the user’s responsibility. 

IBM may have patents or pending patent applications covering subject matter in this 
document. The furnishing of this document does not give you any license to these 
patents. You can send license inquiries, in writing, to the IBM Director of Licensing, 
IBM Corporation, 500 Columbus Avenue, Thornwood, NY, 10594 USA. 

Licensee(s) of this program who wish to have information about it for the purposes of 
enabling (i) the exchange of information between independent created programs and 
other programs (including this one) and (ii) the mutual use of the information which 
has been exchanged, should contact: 

IBM Canada Ltd 

Department 071 

1150 Eglinton Avenue East 

North York, Ontario 

M3C 1H7 

Canada 

This publication contains examples of data and reports used in daily business 
operations. To illustrate them as completely as possible, the examples include the 
names of individuals, companies, brands, and products. All of these names are 
fictitious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 


Programming Interface Information 

This book is intended to help you create programs using the IBM VisualAge C++ for 
OS/2 product. It primarily documents General-Use Programming Interface and 
Associated Guidance Information provided by the VisualAge C++ product. 

General-Use programming interfaces allow the customer to write programs that obtain 
the services of the VisualAge C++ product. 
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Trademarks and Service Marks 


The following terms are trademarks of the International Business Machines 
Corporation in the United States or other countries or both: 
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IBM 

Operating System/2 
OS/2 

Personal System/2 
Presentation Manager 
PROFS 
PS/2 


SAA 

SOM 

Systems Application Architecture 
System Object Model 
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Windows is a trademark of Microsoft Corporation. 


Other company product, or service names, which may be denoted by a double 
asterisk!**), may be trademarks or service marks of others. 
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About This Manual 

This manual describes the IBM VisualAge C++ for OS/2 product (referred to as 
VisualAge C++), its components, available documentation, as well as service and 
support. The VisualAge C++ components give you the ability to edit, compile, link, 
build, debug, analyze and browse C and C++ programs on the 32-bit Operating 
System/2 (OS/2) system. 


Who Should Use This Manual 

This manual is for application and systems programmers who want an overview of 
IBM VisualAge C++ for OS/2. It assumes you have a working knowledge of the C 
and C++ programming languages, the OS/2 operating system, and related products. 


How to Get Help 

There are three kinds of online information available to you while you are using 

VisualAge C++: 

Online documents 

These are complete documents, like the one you are reading now, 
presented online. These documents contain detailed information on the 
different aspects of VisualAge C++. For your convenience, the online 
documents are presented in two formats: 

• Standard format (.INF files). See “Getting Help Inside 
VisualAge C++” on page viii for instructions on opening standard 
format documents from inside VisualAge C++. See “Getting Help 
from the Command Line” on page viii for instructions on opening 
standard format documents from the command line. For a list of the 
VisualAge C++ documents that are available in standard format, see 
“Online Documents Available in VisualAge C++.” 

• BookManager format (on CD-ROM only). See “BookManager 
Books” for details on how to access online documents in this format. 
For a list of the VisualAge C++ documents that are available in 
BookManager format, see “The IBM VisualAge C++ BookManager 
Library” on page 103. 

Contextual help 

Contextual help is available throughout VisualAge C++. This help tells 
you all about the elements that you see in the interface, including menus, 
entry fields, and pushbuttons. 
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How Do I help 

Many of the common tasks that you want to perform with 
VisualAge C++ are described in How Do I help. The How Do I help for 
a task gives you step-by-step instructions for completing the task. There 
is overall How Do I help for VisualAge C++, as well as individual task 
lists for each of its components. 

Getting Help Inside VisualAge C++ 

All three kinds of help are available directly within the VisualAge C++ interface: 

• To get general contextual help for the component of VisualAge C++ that you are 
using, press FI anywhere in the window. 

• To get contextual help on a particular menu, menu item, or button, highlight the 
element and press FI. 

• To get access to all of the help information that is available to you in a particular 
window, click on Hel p in the menu bar at the top of the window. This menu 
includes the following selections: 

- Help Index, an alphabetical list of all of the help topics that are available 
from this window 

- General Hel p, overall help for the window 

- Using Help, general information about the help facility 

- How Do I ..., the How Do I help for the component 

- Product Information, a dialog that shows the level of VisualAge C++ 
being used 

In addition, there are selections that let you open all of online documents that are 
available in VisualAge C++. 

• To get detailed information, open the Information folder in the VisualAge C++ 
folder. In this folder you will find icons for a variety of online documents that 
describe, in detail, the different aspects of VisualAge C++. To open a particular 
online document, double click on its icon. 

Getting Help from the Command Line 

If you want, you can look at the online documents by issuing the view command. 

The installation routine stores the online document files in the \IBMCPP\HELP 
directory. To view the Language Reference , for example, make C:\IBMCPP\HELP 
your current directory (substituting the drive where you installed VisualAge C++ for 
C:) and enter the following command: 

VIEW CPPLNG.INF 
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If you want to get information on a specific topic, you can specify a word or a series 
of words after the file name. If the words appear in an entry in the table of contents 
or the index, the online document is opened to the associated section. For example, if 
you want to read the section on operator precedence in the Language Reference , you 
can enter the following command: 

VIEW CPPLNG.INF OPERATOR PRECEDENCE 

Getting Help for a Keyword or Construct 

If you are editing a file using Editor, you can get help for a keyword or construct by 
highlighting the word and pressing FI. In the other tools, you can get help for a 
keyword or construct by highlighting the word and pressing Ctrl -H. 

BookManager Books 

In addition to standard format, the online documents are also available in 
BookManager format in the CD-ROM version of VisualAge C++. You can read this 
information using either the IBM Library Reader/2 or IBM Library Reader/DOS. Lor 
details on installing and using the IBM Library Reader and BookManager books, see 
the README. ENG file in the root directory of the CD-ROM. 

Online Documents Available in VisualAge C++ 

The following documents are available in standard format: 


Building VisualAge C++ Parts 
for Fun and Profit 

Multimedia Subsystem 
Programming Guide 

SOM Programming 

Reference 

C Library Reference 

Open Class Libraiy 
Reference 

User's Guide 

Control Program Guide and 
Reference 

Open Class Libraiy User's 
Guide 

Visual Builder User's Guide 

Graphics Programming 

Guide and Reference 

OS/2 Bidirectional 
Language Support 
Development Guide 

Visual Builder Parts 

Reference 

1PF Guide and Reference 

OS/2 Tools Reference 

Editor Command Reference 

Kernel Debug Reference 

Presentation Manager 
Guide and Reference 
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Language Reference 

Programming Guide 

Workplace Shell 

Programming Guide 

Multimedia Application 
Programming Guide 

REXX Reference 

Workplace Shell 

Programming Reference 

Multimedia Programming 

SOM Programming Guide 



Reference 
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Introducing IBM VisualAge C++ for OS/2 


IBM VisualAge C++ for OS/2 is a comprehensive and powerful C/C++ development 
package for OS/2 programming. This new, OS/2 Warp-enabled release supports the 
development of C and C++ applications through a full set of tools. The browser, 
editor, compiler, linker, debugger, performance analyzer, visual builder, and database 
access tools work together as an integrated set of tools. These powerful, graphical 
tools are designed to help you as you progress through the development cycle of your 
application. 


VisualAge C++ Components 

This new version of VisualAge C++ includes a variety of components in an 
integrated environment designed to support the development of C and C++ 
applications. These components are: 

• To help you get started 

- Project Smarts - a set of pre-configured projects to start the more common 
development tasks 

- WorkFrame - a fully-conftgurable environment that allows the integration of 
multiple tools 

• To help you code and edit 

- Visual Builder constructs entire applications, complete with windows, menu 
bars, entry fields, and icons 

- Data Access Builder visually allows you to create C++ classes for easy 
access to DB2/2 relational databases 

- IBM Open Class Library incorporates a rich and comprehensive set of 
building blocks 

- The Browser provides fast and easy access to source program information 

- The Editor is a powerful, language-sensitive C++ editor. 

• To help you compile and link 

- The Compiler and Linker generate highly optimized 32-bit code 

- Direct-to-SOM (DTS) support provides a fast, simple way to create high 
quality SOM objects. 

• To help you test and debug 

- The Debugger helps you find and fix errors fast. 

- The Performance Analyzer helps you time and tune your application 
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To Start 

Project Smarts - Create Pre-Configured Projects 

Project Smarts is a tool to help you quickly get started writing VisualAge C++ 
applications. It is a catalog of skeletal applications you can use as a base from which 
to write your own applications. 


Project Smarts - Catalog View 


Use Project Smarts to create a project to 
suit your needs. Select one of the 
following customizable projects and click 
on "Create". 

Available projects: 


C++ Dynamic Link Library 
Data Access Application 
Direct-to-SOM Application 
IPF Context-Sensitive Help 

Description of the selected project: 

A template for building a basic C DLL. 
You can choose to link statically or 
dynamically to the single- or 
multi-threaded C Set ++ runtime library. 


□ 


Create 


Cancel 


Help 


The name of the project to be created. 


Figure 1. Project Smarts catalog 

To use Project Smarts, find the Project Smarts icon in the VisualAge C++ folder and 
double-click on it to open the Project Smarts catalog. It contains a list of common 
applications, including: 

• C Dynamic Link Library 

• C++ Dynamic Link Library 

• Data Access Application 

• Direct-to-SOM Application 

• IPF Context-Sensitve Help 

• IPF Document. 
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• Presentation Manager Application 

• Resource Dynamic Link Library 

• UI Class Library Application 

• Visual Builder Application 

• Workplace Shell Application 

Select an application, click on the Create pushbutton, and Project Smarts creates a 
fully-configured, development-ready project on your desktop. A project represents 
the complete set of data and actions that you need to build a single target, such as a 
dynamic link library (DLL) or executable file (EXE). All the actions, options, and 
environment variables you need to develop a similar application are preconfigured for 
you. Each project is created with template source files to get started quickly on the 
real work, without having to set up the basics every time. Project Smarts applications 
are skeletal, but running, programs. 

A Project Smarts application is distinct from a sample project; it does not teach you 
programming techniques or concepts. The code provides a starting point for you to 
build on when developing your own applications from the code templates. 

WorkFrame - Customize Your Development Environment 

WorkFrame is a fully configurable and open integrating environment that lets you 
mix and match your favorite tools with the ones provided by VisualAge C++. In this 
way you can create and customize your personal development environment. 

WorkFrame gives you the flexibility to work with your files and perform project 
actions that are most effective for you. For example: 

• Use the Build Smarts dialog to quickly switch between the most common build 
options. Through a single dialog you specify whether you want to optimize, 
debug, browse, or analyze your code. Build Smarts temporarily increments your 
existing compiler and linker options to build the project the way you requested. 
Because Build Smarts does not change the compile and link options you may 
have specifically defined for the project, you can still perform your customized 
compile, link, make or build operations through WorkFrame dialogs. 

• You are given a variety of menu choices. WorkFrame provides a menu bar and a 
tool bar in each project window (similar to conventional integrated development 
environments). If you prefer direct manipulation, you can use popup menus and 
drag and drop capability to start actions or change options. 

• You can launch actions defined in a project from a single VisualAge C++ tool. 
For example, if you are editing source files, you can build the project from the 
editor. When the project builds cleanly, you can start the debugger (or any other 
VisualAge C++ tool) from the editor. 
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To Code and Edit 

Visual Builder - An Object-Oriented Visual Application Builder 

Visual Builder is a visual programming tool that can help you create object-oriented 
applications using the C++ programming language. 

Visual Builder gets you started by providing a set of parts as well as interactive 
visual programming tools to work with those parts. You create your applications by 
visually assembling and connecting these prefabricated parts. 

Visual programming with Visual Builder consists primarily of: 

1. Creating a graphical user interface (GUI) from parts using the Composition 
Editor, and, parts supplied by Visual Builder, parts that you create, or both 

2. Connecting the parts so that they interact with each other properly 

3. Generating C++ code using Visual Builder's code generator. 

You can extend Visual Builder by adding your own reusable, custom parts and then 
using these parts in your applications as you need them. You can also import or 
export these parts from other applications. The parts are treated as classes by Visual 
Builder. By developing a library of your own unique parts, tailored to the special 
requirements of your business, even large and complex applications can be created by 
visually arranging and connecting parts. 

Data Access Builder - Build Classes to Access Relational Data 

The Data Access Builder allows you to create new object-oriented database 
applications quickly and reliably by generating the source code and embedded SQL 
for you. Add, update, delete, and retrieve methods are generated for each class. 

These database parts can be used directly in your programs, or you can import them 
into Visual Builder. By using Visual Builder to connect them to the GUI, or other 
parts, you can create high quality applications quickly. 

Some of the key features of Data Access Builder are: 

• Map tables to classes. Create new classes using your existing database tables. 
You can create one class, or many classes, from any table. Both C++ and SOM 
IDL code are supported. 

• Quick or custom mapping. The Data Access Builder offers a quick map feature 
that allows you to do a column-to-attribute mapping. By using inheritance,users 
are able to customize their classes to suit their needs. 
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• Visual display of your mapping. The Data Access Builder graphically displays 
the mapping of your database tables to the object classes. This view allows 
visual editing and uses icons for tables, classes, and arrows to show the 
mappings. 

• Connection and transaction services. Separate services are provided for 
connection and disconnection from your databases. In addition, commit and 
rollback operations are provided to handle transaction services. 

• DB2 Family support. Access DB2/2 in a standalone environment or access DB2 
through the DB2 Client Application Enabler. 

VisualAge Browser - Fast, Easy Access to Program Information 

The Browser is a tool that lets you examine programs developed in VisualAge C++ 
that use large and complex collections of interrelated classes in class libraries. 


| Browser - USERINTF.PDL - Graph Window:! 


File Edit View Actions Options Windows Project Help 

Class IControl — Graph All Base & Derived Classes 


I 49 Items ’_I iHold 



^ IBitmapControl 
IButton 
ICanvas 
ICheckBox 
ICircularSlider 
ICnrCtl 
IComboBox 

ICustomButton 

IDrawingCanvas 

lEntryField 

IFlyText 

IGraphicPushButton 
v IIGroupBox 


Use Mouse Button 2 on top of any object to access PopUp menus 


Figure 2. Graph window showing all base and derived classes of IControl class 

The Browser lets you look at your source code in many different ways. You can: 

• List program objects by type (for example, all classes), by content (members of a 
class), or by components (all files) 

• View relationships between program components graphically, such as class 
inheritance hierarchies, function calls, and included files 

• View and edit the actual source code associated with a selected program element 
using your default editor 

• View online documentation for a class or class member. That is, if you select a 
class or class member, you can directly access the reference manual entry for that 
class or class member. 
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The Browser allows you to view your program either after compilation or by using 
QuickBrowse from within the Browser. 

The graphical user interface consists of two types of Browser windows: 

• A List window displays a list of program elements such as source files, 
functions, and classes 

• A Graph window displays program relationships in a graphical format, for 
example, all nodes in a class hierarchy. You can specify the level of detail you 
want the graph to show, scroll over the graph, zoom in and out, and select 
program elements directly from the graph. 

VisualAge Editor - A Powerful Language-Sensitive Editor 

A new editor has been integrated into VisualAge C++. The Editor lets you build, 
debug, browse, make, or issue other VisualAge C++ commands directly from your 
editing session. 


Kdefine INCLBASE 
ttdefine INCL NOPMPIPI 


ttinclude <os2.h> 


ftinclude <string.h> 


[ttinclude "teststrg.hpp" 


Editor - E:\oview\OVIEW.CPP: 1 


□ 


File Edit View Actions Project Options Windows Help 


Row 12 Column A 

E 


Insert 


[ttinclude <iostrean.h> 


int nain(void) 

{ 

TString testl; 
test 1.setSt ring ("Uelcone t 
testl.showStringC); 
error EDC3G9G: Syntax error - 
cout << "In Oview" « endl; 
DosSleep(5000); // Go t 

return 0; 


[ Build 

HI 

Run 

Ctrl+Shift+R 

Debug 

Ctrl+Shift+D 

Browse 

Ctrl+Shift+O 

Analyze 

Ctrl+Shift+Z 

Make 

Ctrl+Shift+M 

Visual 

Ctrl+Shift+V 

Database 

Ctrl+Shift+A 

MakeMake 

Ctrl+Shift+K 

Edit 

Browse 

a 

i 

Compile 

Package 

Ctrl+Shift+C 

Oview 


Figure 3. The Project Pulldown Menu in the Editor 


It performs all the common editing tasks such as insert, delete, split and join lines, 
find, block, and manipulate text, or undo changes, create and find marks, and move 
between different source views. 
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In addition, to make programming simpler and error free: 

• It is language sensitive. It highlights in different fonts and colors for different 
types of language constructs. Automatic indenting is provided. It dynamically 
performs simple lexical error checking. You can check your work by quickly 
navigating through each error without having to compile or leave the editor. 

• The editor helps you to review and understand the code by presenting several 
views of the source. For example, you can display the function headers in the 
file to quickly see what is in the file and locate a function of interest. You can 
also display the program's flow of control, or insert programming templates. 

• The editor is fully customizable. You can: 

- Change key assignments 

- Write external commands to extend editor capability 

- Create additional parsers 

- Configure the tool bar 

- Select a personality. It supports the look and feel of many common editors, 
such as the OS/2 editor EPM. 

• You can record a sequence of keyboard events as an LPEX REXX command and 
then modify it to be reused as an external command. 

For more information about the using the VisualAge Editor, refer to the Editor 
chapter in the VisualAge C++ User's Guide. 

IBM Open Class Library - A Comprehensive Set of Building Blocks 

The IBM Open Class Library provides you with a variety of building blocks to use in 
your C++ programs. Many of the fundamental components of C++ applications have 
been provided as reusable, extensible classes. IBM Open Class helps you reduce 
your programming effort and avoid coding errors by providing a comprehensive set of 
classes, from basic input/output operations and string handling, through abstract data 
types and user interface support. 

The class libraries are: 

• Collection Classes 

• User Interface Classes 

• Application Support Classes 

• Standard Classes 
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Collection Classes 

The Collection Classes offer a complete set of abstract data types such as sequences, 
sets, bags, and trees. These classes help to reduce errors and simplify the task of 
standardizing the format of data when designing programs or passing data between 
modules. 

The Collection Classes deliver: 

• A choice of several underlying implementations are each optimized for different 
requirements: array, linked list, hash table, AVL tree, and B*-tree. Since these 
implementations provide the same programming interface, as you tune the 
performance of your application, you can select the best underlying 
implementation for the same data type abstraction without changing your source 
code. 

• Completeness of abstract data types. For instance, all abstract data types have 
complete sorted and keyed versions. 

• Flexible parameterization. You can implement your own memory manager. 

• Flexible definition of element operations. Default equality and and comparison 
operators can be overridden with your own definition. 

User Interface Classes 

The User Interface Classes provide a comprehensive set of classes for programming 
graphical user interfaces on OS/2, AIX, and Windows. These classes simplify the 
coding of GUI applications and result in a more portable, reusable object-oriented 
user interface. 

IBM Open Class gives you a consistent way to write user interface code without 
having to program to the low-level system APIs. IBM Open Class exploits the 
underlying operating system services. For example, the user interface classes exploit 
Motif services on AIX and Presentation Manager services on OS/2. 

The User Interface Classes let you: 

• Create and display windows using title bars, varying sizes and styles 

• Include controls such as menus, buttons, text, list boxes, sliders, notebooks, and 
containers, withnew support for animated pushbuttons 

• Draw canvases with flexible window layouts that allow automatic redrawing and 
aligning of cells independent of the display device 

• Provide direct manipulation (drag and drop) support 

• Add multimedia with classes for constructing many different devices like a midi 
sequencer, wave file playing and editing, digital video players and recorders, 
programmable CD players, amplifier and mixer, and the master audio control 


8 Welcome to VisualAge C++ 



Introducing VisualAge C++ 


• Provide 2-D graphics support for drawing primitives (lines and arcs) plus support 
for reading and displaying various graphic formats, such as GIF, PIF, BMP, and 
others 

• Create and manage a tool bar, including being able to move, change, and resize it 

• Create parts, using the parts notification framework, for Visual Builder 

• Communicate between OS/2 applications running on the same machine using 
Dynamic Data Exchange (DDE) 

• Display help, define contextual help, and handle help keys, plus new fly-over 
help that comes up automatically when the mouse pointer is on an object 

• Cut, copy, and paste to and from the clipboard. 

You can use all of these classes as provided or extend and tailor them, combine them 
with other class libraries to develop complete object-oriented applications. 

Application Support Classes 

The Application Support Classes provide the basic abstractions required during the 
creation of most C++ applications, including: 

• String manipulation classes 

• Date and time classes 

• Error handling and trace classes. 

The string classes define a data type for strings and provide member functions that let 
you perform a variety of data manipulation and management activities. They provide 
capabilities beyond those available with standard C strings in the string.h library 
functions. 

The string classes have the following capabilities: 

• String buffers are handled automatically 

• Strings can contain both SBCS and MBCS characters 

• Strings can be indexes by character or by word 

• Strings can contain null characters (there are no restrictions on the contents of a 
string object). 

The string class members allow you to: 

• Use strings in input and output 

• Access information about strings 

• Compare strings 

• Test the characteristics os strings 

• Search for characters or words within a string 

• Manipulate and edit strings 

• Convert strings to and from numeric types 

• Format strings by adding or removing white space. 
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The date and time classes provide you with data types to store and manipulate date 
and time information. With these classes you can create date and time objects, and 
use member functions to do the following: 

• Write date and time objects to an output stream 

• Access detailed information about dates or times 

• Compare dates or times 

• Add or subtract days from a date, or hours, minutes, or seconds from a time 

• Convert between date formats or time formats. 

The exception classes provide the framework for throwing exceptions within the class 
libraries. The trace class helps in tracing exceptions. 

Standard Classes 

The Standard Classes consist of the standard I/O Stream library and the Complex 
library. 

The I/O Stream Library provides you with the facilities to deal with many varieties of 
C++ input and output. You can derive classes from this library to customize the input 
and output facilities for your own particular needs. 

The Complex Library gives you the capability to manipulate complex (imaginary) 
numbers and perform standard mathematical operations on them. 


To Compile and Link 

VisualAge Compiler and Linker - Generate Highly-Optimized 32-bit Code 

The Compiler and Linker generate highly optimized C and C++ code and make 
efficient use of disk and memory space. To produce the most efficient code possible, 
VisualAge C++ uses such advanced optimization techniques as: 

• Instruction scheduling 

• Code hoisting 

• Global register allocation 

• User code inlining 

• Intermodule optimizations. 

Code can be optimized for any Intel architecture processor from the i386 to the 
Pentium. 

New memory management algorithms in the C and C++ runtimes make efficient use 
of memory to reduce the amount of memory overhead in your programs. 
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If you need to minimize how much disk space your application uses, the compiler has 
a new minimize size option. While generating code for debugging, disk space can 
also be saved with the new set of debug support options. This can reduce the size of 
debug-ready executables without the loss of debug information. Also, the line 
number only debugging support offers the option of a lower level of debug support 
with almost no increase in executable size. 

In addition, linker optimization options improve resolution of function and member 
function calls. These options can significantly reduce the size of your application 
files. 

The VisualAge C++ compiler and linker are fast and highly usable. Compile time 
has been improved, especially with the use of improved precompiled headers. The 
new 32-bit linker with automatic template resolution (without prelinking) improves 
link time over that of the previous linker (LINK386). It also supports most of the 
options of the previous linker with the new linker options. 

Direct-to-SOM (DTS) Support - Create High Quality SOM Objects 

Direct-to-SOM (DTS) is a standard for implementing flexible and reusable objects, 
supported by the tools of VisualAge C++. DTS combines standard C++ syntax with 
IBM's System Object Model (SOM). 

With VisualAge C++ you generate SOM objects directly from the C++ compiler by 
turning on a compiler option. The compiler generates the corresponding Interface 
Definition Language (IDL) for use in interlanguage or Distributed SOM (DSOM) 
applications. The VisualAge C++ Browser shows SOM objects in a different color 
than a C++ object. The Data Access Builder has options to generate SOM classes (or 
IDL code). The VisualAge C++ Debugger provides debug support for SOM objects. 

SOM improves your C++ programming productivity: 

• Release to release binary compatibility removes the dependency between the code 
that implements a class and the code that uses it. This compatibility allows you 
to create and deploy a new version of a class, with added function or data 
members, and with inheritance from new base classes, without the need to 
recompile unchanged code. By packaging your SOM class in a DLL, you can 
replace the existing DLL with the new one, and all applications that use it will 
continue to run. 

• Extensive dynamic facilities let you query properties of objects and classes, and 
the use of the classes and methods whose names are not known until execution 
time. Applications can be extended by incrementally installing new applications 
that the application is told about through a configuration file or by user input. 
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• Distributed SOM (DSOM) allows access to objects between processes, or across 
networks. 

With DTS you write C++ directly and this lets you use C++ features in your SOM 
classes that were not available before DTS. These features include templates, 
operators, constructors with parameters, default parameters, and static members. 


To Test and Debug 

VisualAge Debugger - Find and Fix Coding Errors Fast 

The Debugger is your primary tool for detecting and diagnosing coding errors. 


p| OVIEW Thread 1 |f 

r:i- w: „r>_ - 


File View Break] 
Project Help 

'lihiihiihilhilhiLhlhiihiil - 


1 ttdefine INCL_B 
2| ttdefine INCL_N 
#include <os2. 
ttinclude <stri 
ttinclude "test 
ttinclude <iost 


Program Monitor 


□ 


1 File Edit Options Windows Help 

El testl 



Beststring "X\x05\x04" 



— 



int main(void) 

{ 

TString testl; 

// testl.setString ("Welcome to UisualRge C++"); 
test1.showString(); 


cout « In Ooiew « endl; 


□ 


DosSleep(5000); 
return 0; 

> 


// Go to sleep for 5 seconds.. 


OVIEW.CPP 


IOSTREAM.H 


Figure 4. Program monitor and a debug source view 

The user interface gives you the ability to debug at the source level, as well as 
providing access to common debugger functions such as step, run, set breakpoints, 
monitor variables, display the call stack, display registers, and display storage. 

The Debugger provides the following built-in tools to help locate problems and fix 
code quickly: 

• The Window Analysis tool displays a three-dimensional view of all the windows 
your program creates, including the window characteristics and relationships 
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• The Message Queue Monitor actively monitors Presentation Manager messages 

• C++ debugging features include template support, locate overloaded functions, 
class display, and debugging code in include files 

• Automatic heap checking to help isolate memory management problems by 
checking for memory overwriting each time your program starts executing. 

VisualAge Performance Analyzer - Time and Tune Your Code 

The Performance Analyzer helps you time and tune your applications by collecting 
execution data in a trace file and presenting it in several graphical diagrams. 


IH 0V1EW.TRC - Call Nesting 


Trace file Edit View Options Project Help 

Trace description: 

Fil ters :_ none 

~~1 main 

— I TString::setString(char*) 

~I strcpy 


TString::showString() 

~I ostream::operator<<(ostream&(*)(ostream&)) 


ostream::operator<<(ostream&(«)(ostream&)) 


J > 


Figure 5. Call Nesting diagram 

The trace file lets you : 

• See a detailed record of function calls and returns. Locate the areas within an 
application where a disproportionate amount of time is spent. 

• View the function call stack any place in the application to see the history of 
events leading up to the point the program stopped. 

• Determine multithread interactions and expose problems with critical sections by 
looking at the sequencing of procedures across threads. 

Using these diagrams, you can improve the performance of an application, examine 
what led to certain faults, and understand what happens when your application runs. 
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Getting Started with VisualAge C++ 


This part of the overview introduces you to the WorkFrame development environment 
and the VisualAge C++ components integrated with a WorkFrame Project. 

By using a sample project and a simple program example, you invoke and use the 
VisualAge C++ components. 


Project Icon View 

A WorkFrame project provides an integrated environment through which you can 
access VisualAge C++ components. You learn how to use some of those components 
through the Icon View of a WorkFrame project. 

1. Locate the Samples folder in the VisualAge C++ folder and open it. 
(Double-click mouse button 1 on the folder to open it.) 

2. Find and open the project named Welcome. 



Figure 6. Welcome Project - Icon View 


© Copyright IBM Corp. 1995 
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The prominent features of the window, from top to bottom, are: 

• the Menu bar 

• the Project toolbar, which includes a Parts filter control with a drop-down list 
box, 

• the project Parts container 

• the project Monitor 

• and the Monitor toolbar. 

If the toolbars are not visible, open the View menu item and select Toolbar —» 
Show. If the project Monitor is not shown, either click on the monitor icon in 
the Monitor toolbar, or select Show on the Monitor pulldown menu. 

3. Click on Project in the menu bar to open the pulldown menu. 



Project Selected Monitor 

Build 

a 

Run 

Ctrl+Shift+R 

Debug 

Ctrl+Shift+D 

Edit 

Ctrl+Shift+E 

Browse 

Ctrl+Shift+O 

Analyze 

Ctrl+Shift+Z 

Make 

Ctrl+Shift+M 

Visual 

Ctrl+Shift+V 

Database 

Ctrl+Shift+A 

MakeMake 

Ctrl+Shift+K 


Figure 7 . Project Pulldown Menu 

Project-scoped actions are available in the pulldown menu. Build, Run, and 
Debug are examples of project-scoped actions. 

Project-scoped actions can be added to the Toolbar to give you a convenient way 
to launch the actions. 
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4. File-scoped actions are available on the pop-up menus of the objects represented 
in the Parts container. For example, move the mouse pointer to the .cpp object 
and click mouse button 2. 


Open 

a 

Settings 



Copy... 

Move... 

Create shadow... 

Delete... 

Edit i+j 

Browse 

Compile Ctrl+Shift+C 
Package 


Figure 8. Pop-up Menu for OVIEW. CPP 

The pop-up menu contains such file-scoped actions as Edit, Compile, and 
Package. 

5. To see what the Parts filter does, move the cursor to the Parts filter entry field 
and enter *.cpp. 

Only the .cpp objects are displayed in the parts container. The other object types 
are not shown. 
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If you have a project with a large number of parts, the Parts Filter is a convenient 
way to specify which parts you want to display and work with. You can also use 
the drop-down list box to select from types that are available to the project. 



a 

a 

Smarts 

Tools 

Help 


□ 


Project Selected Monitor View Options Help 


g' OVIEW.CPP 
E TESTSTRG.HPP 
g IMP.CPP 


ModuleDef 

RCSource 

MsgSource 







> 

Build 

Run 

Debug 

Edit 


p 

Q. 

El 

m 

El 

a 

m 

StOC 

Repeat 

History 

Errors 

Save 

Erase 

Show 


Figure 9. Parts Filter Drop-Down List Box 

6. You will use more of the functions of the project Icon View in the sections that 
follow. 

For specific information about the Menu bar. Tool bar. Parts filter. Parts 
container, and Monitor window, access General help from the Help pulldown of 
a WorkFrame project window, or refer to the WorkFrame section of the User's 
Guide. 

For additional information about the concepts and functions referenced within this 
Project Icon View section, see: 

• “A WorkFrame Project” on page 79 

• “Project Icon View” on page 80 

• “Project-Scoped Actions” on page 82 

• “File-Scoped Actions” on page 82. 
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Edit and Compile 

A simple edit and compile example shows you how actions can be started front the 
project and from VisualAge components that are integrated with the project. 

1. The oview.cpp file has a coding error in it. When you invoke the Build action, 
a compile-time error occurs during the build process. 

2. In the Welcome project icon view, open the Project pulldown menu and select 

Build. 

The results of the Build action appear in the project's Monitor window and the 
following error message is generated: 

Syntax error - expected ” and found “testl 

3. Locate the syntax error message in the Monitor window. (You may have to 
scroll back in the Monitor window to find it.) To open the Editor, do one of the 
following: 

• Select the error (click mouse button 1 on the error line), and then select the 
Errors button on the monitor toolbar, or, 

• Move the mouse pointer to the error line and double-click mouse button 1. 


Smarts 

a 

Tools 

n 

Help 

— 


Ml Welcome 


Project Selected Monitor View Options Help 



A 

# 

m 

Build 

Run 

Debug 

Edit 


| tlEiawai 
|^ ! OVIEW.CPP 
[^ TESTSTRG.HPP 
[^ OVIEW.MAK 


IMP.CPP 


NMAKE : fatal error U1077: ■D:\0S2\CMD.EXE' : return code ’12* 
Stop. 

Action complete, RC=2 


e 

G 

El 

S’*. 

El 

a 

e 

Stop 

Repeat 

History 

Errors 

Save 

Erase 

Show 


|Edit the source of the error highlighted in the monitor window 


Figure 10. Error Selected in the Project Monitor window 
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The Editor window opens and the cursor is at the location in the source file 
where the error is detected. The error message generated during the build also 
appears in the source file following the line where the error is detected. 


|Q 

File 


I 8 ' ■ - ZZI 


Editor - E:\oview\OVIEW.CPP: 1 


□ 


Edit 

al feilfc ilQm b 
Row 12 Column A 


View Actions 

#\ bU]bj|b|c^|p 


Project Options Windows Help 


Insert 


Z!3 


__+-3-+-4-+-5-+-5- 


Ittdefine INCL 


ttdefine INCL 


BASE 
NOPMAPI 


[ftinclude <os2.h> 


8include <string.h> 


ittinclude "teststrg.hpp" 


[8include <iostrean.h> 


int nain(void) 

{ 

TString testl; 

test 1.setSt ring ("Uelcone to UisualAge C++") 

[test 1. showstring (); 

error EDC309G: Syntax error - expected and found "testl". 
cout << "In Oview" « endl; 

DosSleep(50OO); // Go to sleep for 5 seconds... 

return 0; 


Figure 11. A source file error highlighted in the Editor 

4. Correct the error by adding the semicolon (;) to the end of the statement 
testl.setString ... . Press F3 to close the Editor and click on the Yes pushbutton 
in the Editor Warning dialog to save the changed file. 

5. Select the Repeat button in the Monitor toolbar to re-run the last action - the 
Build action. 

The Build action completes successfully. 

This edit and compile example illustrates the integration and interaction of the Editor 
with the WorkFrame project. 

VisualAge components integrated in a WorkFrame project, have a Project menu item 
on the menu bar. In each of the components, the Project pulldown menu gives you 
direct access to the other VisualAge components integrated with the WorkFrame 
project. 

For specific information about the Editor, see the Editor section of the User's Guide. 
You can also access General help or How do I? help from the Help pulldown menu 
in the Editor. 
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The next topic, “Use the Debugger” on page 21, shows you how to perform the 
debugging step of an edit, compile, and debug cycle. 


Use the Debugger 

In this part, you create a run-time error in the source code, and then use the 
VisualAge C++ Debugger, to locate and correct the error. 

Note: This section is dependent on the successful completion of the items in “Edit 
and Compile” on page 19. 

1. In the Welcome project, open the pop-up menu of oview.cpp (click mouse button 
2 on oview.cpp), and select Edit to open the file in an edit session. 

2. To simulate a coding error, add double slashes (//) to the line coded as 
testl.setString ("Welcome to VisualAge C++") to comment it out. 

Press F3 to close the Editor and click on the Yes pushbutton in the Editor 
Warning dialog to save the changed file. 

3. In the Welcome project, select the Smarts button on the project toolbar. The 
Build Smarts window that opens indicates that the project will be built for 
debugging. 


Build Smarts 


a Enable Build Smarts to add support for the following VisualAge C++ features: 

3 Debugger 

□ Browser 

□ Performance Analgzer 

□ Optimizer 

a Generate a make file 
a Build ang subprojects first 

User macro sets 

Define Remove 

□ Development 

□ Production 

| OK | Cancel Help 


Figure 12. Build Smarts window 

Click on the OK pushbutton. You are now ready to rebuild the project. 

Build Smarts is a quick way to configure the project build options so that you 
can use VisualAge C++ components that require special build support. By 
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default. Build Smarts will make all project targets debuggable (as indicated by 
the Debugger check box state). 

4. Open the Project pulldown menu and select the Build —» Rebuild all cascade 
menu item to rebuild the project. 

The project build cycle is displayed in the Monitor window and the project builds 
successfully. 

5. Run the program to display its output in the Project monitor - click mouse button 
2 on oview.exe. On the pop-up menu, click on the arrow beside Run to open the 
cascade menu and select Monitored. 



■ □ 

Project Selected Monitor View Options Help 

Halall* *IUiUlsl®! 


[^ OVIEW.PDB |M S OVIEW.CPP 
(n) OVIEW.EXE TESTSTRG.HPP 

1^, OVIEW.OBJ OVIEW.MAK 

[^ IMP.OBJ |gf IMP.CPP 

OVIEW.$MM 


- -1 

Starting Run::Monitored 
* E:\WELCOME\OVIEW.EXE 

In Oview 

Action complete, RC=0 


< 

> S 


imiSIIQleilalBI 



Figure 13. Unexpected Run output in Project Monitor window 


The program runs and its output is sent to the Monitor for viewing. The 
expected output. Welcome to VisualAge C++, does not appear in the window. 

6. To start the Debugger, select the Debug button on the Project toolbar, or open 
the Project menu and select Debug. (The Program profile warning may appear. 
Select the No pushbutton. ) 
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Three windows open: 

Debugger Control 
Debug Appl 
Source: 


|n) Debug Appl - OVIEW.EXE = □ 





File View Breakpoints Monitors Run Options Windows 



Figure 14. Debugger windows - Control, Source, and Application 


7. Since the expression for the variable testl did not appear in the program's output, 
open the Monitors pulldown menu in the Source window and select Monitor 
expression. 
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8. Type testl in the Expression entry field of the Monitor expression window and 
select the Program Monitor pushbutton. 


Monitor Expression 


Expression 

testl 

Context 

File OVIEW.CPP 

Line 8 

View Source 
Thread 1 


Add to: _ 

Program monitor ^ 

Popup monitor 
Private monitor 
Storage monitor 


Cancel Help 


Figure 15. Monitor Expression window 


A Program Monitor window opens. It shows that the testString expression of 
testl is not allocated. 




File Edit Options Windows Help 



B testl 



| testString|liot allocated. 







Figure 16. Program Monitor window 

9. In the Source window, single step through the program by clicking mouse button 
2 to execute each line of the program. 
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When the cout statement is executed, the allocation for teststring in the Program 
Monitor window is not the expected text. This indicates that testl is not being 
initialized to Welcome to ... . In the Source window you can see that testl has 
been commented out. 


pi OVIEW Thread 
File View Break| 
Project Help 

riihiriilTilHhiPlhlPilTilTilJ I 


Program Monitor 


File Edit Options Windows Help 


□ 


0 testl 

| test St ring| "X\xQ5\x04" 


ttdefine INCL_B 
ttdefine INCL_N 
#include <os2. 

It include <stri 
ttinclude ''test 
It include <iost 

int main(void) 

{ 

TString testl; 

// testl.setString ("Welcome to Uisualfige C++"); 
test1.showString(); 


i cout « "In Oview" « endl; 


□ 


DosSleep(5000); 
return 0; 

> 


// Go to sleep for 5 seconds.. 


OVIEW.CPP 


IOSTREAM.H 


Figure 1 7. Results of the expression allocation 


10. To open an Editor session at a specific point in the source file, double-click on 
the background beside a particular statement in the Debugger Source view. In 
this case, double-click on the background beside testl.setString .... 
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The oview.cpp source file opens in the Editor and the cursor is at the line 
designated by the double-click action in the Debugger. 


Editor - E:\OVIEW\OVIEW.CPP: 1 


File Edit View Actions Project Options Windows Help 

blMiajoUi dUb h c+ p 


Row 11 Column 1 Insert 

j— + - 1 - + -2-♦-3-+-4-*-5-+-6-«--7 -j 


A 

ttdefine INCL BASE 
ttdefine INCL NOPMAPI 
ftinclude <os2.h> 

#include <strinq.h> 
ttinclude "teststrq.hpp" 

#include <iostrean.h> 

int nain(void) 

{ 

TString testl; 

// testl.setString ("Uelcome to UisualAge C++"); 

testl.showStringO; 

cout « "In Oview" « endl; 

DosSleep(50G0); // Go to sleep for 5 seconds... 

•v 

_i_i > 


_ 


Figure 18. Editor opens at designated line source file 

11. Remove the double slashes (//) from the line coded with testl.... Press F3 to 
close the Editor and click on the Yes pushbutton in the Editor Warning dialog 
to save the changed file. Also close the Debugger by pressing F3 in any of the 
Debugger windows. 

The debugger needs to be closed to free the executable (oview.exe) for the 
project build cycle. 
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12. Rebuild the project by selecting the Build —* Rebuild all cascade menu item on 
the Project pulldown menu. After the project builds successfully, run the 
executable (select Run —* Monitored in the Project pulldown menu) and you 
will see that the expected text appears in the project Monitor. 


Welcome 


Project Selected Monitor View Options Help 


« □ 


gilaiml 


* OTB 


[5l OVIEW.OBJ 
[5l IMP.OBJ 
[5, OVIEW.$MM 
|g' OVIEW.CPP 


[5l TESTSTRG.HPP 
[5, OVIEW.MAK 
|a' IMP.CPP 


Startinq Run::Monitored 
* E:\WELCOME\OVIEW.EXE 
Welcome to VisualAge C++ , 
In Oview 


Action complete, RC=0 

< - 


TTsITTf] liMal lei 


Figure 19. Successful Run output in the Project Monitor window 

13. Leave the Welcome project open for the next topic, “Use the Browser” on 
page 28. It shows you how to browse the structure of the classes used in the 
sample program. 

This series of steps introduced you to Build Smarts, the Debugger, and the Debug 
Program Monitor. In addition, you invoked the Editor while still in the Debug 
session. 
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For specific information about using the Debugger, see the Debugger section in the 
User's Guide. 

You can also access: 

• General help 

• Help index 

• How do I? help 

from the Help pulldown menu in any Debugger window. 

For additional information about the concepts and functions referenced within this 
Use the Debugger section, see: 

• “Build Smarts” on page 82 

• “Program Profile” on page 84 

• “Debugger Control” on page 84 

• “Debugger Source Windows” on page 86 

• “Step Commands” on page 89. 


Use the Browser 

In this part, you use Build Smarts to set options so that the project executable may 
be browsed with the Visual Age C++ Browser. Using the Browser, you will see the 
relationship and inheritance of classes in both a list format and a graphical format. 

Note: This section is dependent on the successful completion of the items in “Edit 
and Compile” on page 19. 

1. In the Welcome project, select the Smarts button on the project toolbar. 

In the Build Smarts window that opens, select: 

a. Enable Build Smarts to... 

b. Browser 

c. Generate a make file .... 

d. Click on the OK pushbutton. 

Select the Build —* Rebuild all cascade menu item on the Project pulldown 
menu. 

The project build cycle is displayed in the project's Monitor window and the 
project builds successfully. 

2. Select Browse on the Project pulldown menu. 

As the Browser starts up, a Browser New User Help window opens. Click on 
OK to close the window. 
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A Browser List Window 1 opens with a list of all the classes used in the 
program. 


nil Browser - oview.exe - List Window:1 


- □ 


File Edit Actions Options Order Windows Project Help 

List All Classes j 93 Items □ Hold 


TStnng 


AVAILDATA 

CONTEXT 

.COUNTRYCODE 

.COUNTRYINFO 

DATETIME 

_DENA1 

.DEVOPENSTRUC 
DRIVDAT A 
EAOP 
_EAOP2 
.EASIZEBUF 

.EXCEPTIONREGISTRATIONRECORD 

EXCEPTIONREPORTRECORD 


|Use Mouse Button 2 on top of any object to access PopUp menus 


Figure 20. Browser List Window 1 listing all classes 


The menu bar of the Browser list window also has a Project menu item. The 
pulldown menu displays project actions that invoke other VisualAge components 
directly from the Browser. 

The Action Status Bar (below the Menu bar) shows what object and action 
produced the list. A count field on the right shows how many program elements 
are in the list. The Hold checkbox, when checked, keeps the current list window 
from being replaced if another list window selection is made. 
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3. Open the Find dialog by selecting Find... from the Edit pulldown menu. Enter 
istream as the search text. Ensure that Case Sensitive is not checked, and select 
the Find pushbutton. 

The list scrolls to the istream class. 


Browser - oview.exe - List Windowri 

- □ 

File Edit Actions Options Order Windows Project Help 

(List All Classes 

93 Items □Hold 


-fpreg 
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ios 
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iostream 
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Find 


Apply 
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Help 


Use Mouse Button 2 on top of any object to access PopUp menus 


Figure 21. Browser List Window 1 listing all classes 


4. Click mouse button 2 on istream to open a menu, and select List Members with 
Inheritance to find out more about istream and its members. 

Both istream and ios are listed in the window. 
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5. Expand istream by clicking on the + icon. 

Public, protected, and private access methods are listed. If you expand these 
further, you begin to see the level of detail the Browser provides. 


M 

Browser - oview.exe - List Window:! 

| ° □! 

File Edit Actions Options Order Windows Project Help 


Class istream — List Members with Inheritance 
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0 istream 

Ejj] ffircna 
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0 functions 
0 protected 
0 private 
0 ios 


|Use Mouse Button 2 on top of any object to access PopUp menus 


Figure 22. List Members with Inheritance for istream 

A quick way to expand the list - click mouse button 2 on the background of the 
window and select Expand all in the menu. 

6. For a different view of the members, select Type on the Order pulldown menu 
to list the members by type. 

The types are: 

• constructors/destructors 

• functions, 

• types 

• variables. 
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If you expand variables, you will see that they are subdivided by public, 
protected, and private access methods. 


in 


■ ° □ 
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|Use Mouse Button 2 on top of any object to access PopUp menus 


Figure 23. List Members by Type for istream 

7. In the Order pulldown menu, select Access. 


in 
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|llse Mouse Button 2 on top of any object to access PopUp menus 


Figure 24. List Members by Access for istream 

The classes are now organized by access method. 


32 


Welcome to VisualAge C++ 







Getting Started 


The next section describes how to generate a graphical view of the classes used in a 
program, and then shows you a more detailed illustration of the Browser. 

Browser Graphs and Functions 

This section shows you a graphical view of the classes used in the sample program, 
and then takes you through a more detailed illustration using the Browser and the 
User Interface Classes. 

1. Select Class on the Order pulldown. In the refreshed list window, click mouse 
button 2 on istream and select Graph All Base &Derived Classes. 

A graphical view of the classes is displayed. 

2. Adjust the slider on the left of the graph area to zoom the graph in or out to see 
the text in the nodes. 

As you select each node in the graph, both the node and the text in the list area 
on the right are highlighted. If you select the text in the list area, the 
corresponding node in the graph is highlighted. 



Figure 25. Graph All Base & Derived Classes for istream 
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3. Select Show Include File Graph on the Actions pulldown menu. 

A graph showing the include file structure is displayed. This shows where the 
classes, types, variables, and code included in the program originate. 


m 


Browser - oview.exe - Graph Window:! 


° □ 


File Edit View Actions Options Windows Project Help 

Show Include File Graph 


15 Items □Hold 



bsedos.h 

bseerr.h 

bsememf.h 

bsesub.h 

bsetib.h 

bsexcpt.h 

cppopa3.cpp 

imp.cpp 

iostream.h 

os2.h 

os2def.h 

oview.cpp 

string.h 

teststrg.hpp 


LU — ■ _ _ 1 ■ MJJ II. 

(Use Mouse Button 2 on top of any object to access PopUp menus 


Figure 26. Show Include File Graph 

4. For a more detailed illustration of the Browser, select Load —» User Interface 
Classes from the File pulldown menu. 
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The List window refreshes with a list of all classes defined in the User Interface 
classes. 


| Browser - USERINTF.PDL - List Window:1 


File Edit Actions Options Order Windows Project Help 

List All Classes 817 Items □Hold 


CursorData 


l3StateCheckBox 

l3StateCheckBox::Style 

!3StateCheckBox::Style::NegatedStyle 

lAccelTblHandle 

■Accelerator 

lAccessError 

lAnchorBlockHandle 

lAnimatedButton 

IAnimatedButton::Style 

IAnimatedButton::Style::NegatedStyle 

lAnimatedButtonData 

■Application 

lAssertionFailure 

IAvlKeySortedSet<class Element,class Key> 

lAvIKeySortedSetlmpl 

lAvIKeySortedSetlmpINode 

IBase 

IBase::Version 

IBaseComhoBox _ 

I 

Use Mouse Button 2 on top of any object to access PopUp menus 


Figure 27. List window showing all classes in the User Interface classes 


5. Open the Find dialog by selecting Find... from the Edit pulldown menu. Enter 
ilistbox as the search text, ensure that Case Sensitive in not checked, and select 
the Find pushbutton. 
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The list scrolls to the IListBox class. 


1531 Browser - USERIHTF.PDL - List Window:! _ 

File Edit Actions Options Order Windows Project 
(List All Classes 817 Items 

IKeyAlreadyExistsException 
IKeyboardEvent 
IKeyboardEventPrivateData 

ILinkedSe * ■aiiTiM 

ILinkedSe —n 

ILinkedSe Flnd: ,,stbox 
ILinkedSe Options 

■LmkedSe QCase Sensitive 3 Wrap Around 

IListBox::? Find | [Apply. Cancel Help 
IListBoxD; 

IListBoxDrawItemEvent 

IListBoxDrawItemHandler 

IListBoxDrawltemHandler::DrawFlag 

IListBoxDrawltemHandler::DrawFlag::NegatedDrawFlag 

IListBoxNotifyHandler 


Project Help 
817 Items □ Hold 


3 Wrap Around 


Apply | 


Use Mouse Button 2 on top of any object to access PopUp menus 


Figure 28. Finding a class name 

6. Click mouse button 2 on IListBox to open the Class pop-up menu, and select 
Graph All Base Classes 
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The Graph window shows the inheritance hierarchy for IListBox and 
alphabetically lists the classes that appear in the graph. 


g|| Browser - USERINTF.PDL - Graph Window:! 


□ 


File Edit View Actions Options Windows Project Help 

Class IListBox — Graph All Base Classes 7 Items □Hold 

I iVBasel RllBase 


I Notifier 


I Window 


I Control 


IBaseListBox 


IListBox I 


|j<J 


IBaseListBox 

IControl 


IListBox 


INotifier 

IVBase 

IWindow 


Use Mouse Button 2 on top of any object to access PopUp menus 


Figure 29. Graph window showing all base classes of the IListBox class 

7. Click mouse button 2 on the node of the IControl class object in the graph, or on 
IControl in the alphabetical list. 
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8. Select Graph All Base & Derived Classes on the pop-up menu. 
A new graph shows the classes that inherit from IControl. 


Browser - USERINTF.PDL - Graph Window:1 


File Edit View Actions Options Windows Project 

(Class IControl — Graph All Base & Derived Classes 


□ 


Help 



! 49 Items □ Hold 
± llBitmapControl * 
jlButton 
ICanvas 
ICheckBox 
ICircularSlider 
ICnrCtl 

IComboBox _ 

ICustomButton 
IDrawingCanvas 
lEntryField 
IFlyText 
IGraphicPushButton 
v jIGroupBox 

_ _| 


jUse Mouse Button 2 on top of any object to access PopUp menus 


Figure 30. Graph window showing all base and derived classes of IControl class 


You can use the Overview window to quickly view portions of the graph and 
zoom in or out. This is an alternative to using the slider bar and the scroll bars. 


'A 


Graph - Overview:! 




£2 


Figure 31. Overview window 


9. Close the Browser by pressing F3 in any of the Browser windows. 


38 Welcome to VisualAge C++ 







Getting Started 


There are many other functions and views available in the Browser. For a complete 
description of the Browser, see the Browser section in the User's Guide. 

You can also access: 

• General help 

• Help index 

• How do I? help 

from the Help pulldown menu in any Browser window. 

For additional information about the concepts and functions referenced within this 
Use the Browser section, see: 

• “Browser Overview Window” on page 90. 


Use the Performance Analyzer 

The VisualAge C++ Performance Analyzer traces the execution of a program and 
creates a trace file. The trace file contains a chronological sequence of events that 
occur during the execution of your program. This trace data can be viewed and 
analyzed in diagrams. Programs must be compiled and linked with the proper options 
before a trace file can be created and the Performance Analyzer can be used. 

Note: This section is dependent on the successful completion of the items in “Edit 
and Compile” on page 19. 

In this part you use Build Smarts to build the project for the Performance Analyzer, 
and then view the results in the Performance Analyzer diagrams. 

1. In the Welcome project, select the Smarts button on the project toolbar. 

In the Build Smarts window that opens, select: 

a. Enable Build Smarts to... 

b. Performance Analyzer 

c. Generate a make file .... 

d. Click on the OK pushbutton. 

Select the Build —» Rebuild all cascade menu item on the Project pulldown 
menu. 

The project build cycle is displayed in the Monitor window and the project builds 
successfully. 

2. In the Welcome project, click mouse button 2 on oview.exe to open the pop-up 
menu, and select Analyze. 
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Select OK in the Performance Analyzer - Specify Profile Location dialog that 
opens. (You can change the path for the profile information or leave it as 
specified.) 

A Performance Analyzer Window Manager window opens, (it remains open 
while the Performance Analyzer is running), and a Trace Generation window 
opens. 



Figure 32. Window Manager window 



Figure 33. Trace Generation window 
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3. Click on the Trace pushbutton to start the trace operation. 

An Application Monitor opens to show the progress of the trace. When the 
trace operation ends, a Trace File - Analyze window opens with a choice of five 
diagrams to view. 


Analyze Trace 


Trace File Name: 
E:\OVIEW\OVIEW.TRC 


Find... 


Diagrams 

□ Call Nesting 

0 Dynamic Call Graph 

□ Execution Density 

□ Statistics 

□ Time Line 


OK t 


Cancel Help 


Figure 34. Trace File - Analyze window 


In addition, a trace file (oview.trc) has been created. Trace files can become 
large and difficult to manage. You can limit the amount of data collected in the 
trace file by selecting specific components to enable or disable during the trace 
operation. For specific information about customizing a trace file, see the 
Performance Execution Trace Analyzer section of the User's Guide. 

The next section describes the use of the Dynamic Call Graph. 
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Dynamic Call Graph 

In this section you use the Analyze Trace window that you opened in the previous 
section, to select and generate a Dynamic Call Graph. 

1. Click on the Dynamic Call Graph check box in the Analyze Trace window. 
Then click on the OK pushbutton to generate the diagram. 

A Dynamic Call Graph window opens, and the Window Manager window is 
updated to show which diagram is open. 


Trace description: 
[Filters: none 

ISeLected obj ect: main 




OVIEW.TRC - Dynamic Call Graph 


- □ 


Trace file View Options Project Help 



l<l 


Figure 35. Dynamic Call Graph diagram in scaled format 


By default, the nodes and the arcs in the graph are scaled to show the relative 
time spent in the nodes and the number of calls between nodes. 
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Each time you open a diagram, the Window Manager window is updated to 
show which diagrams are open. If you double-click on a specific diagram in the 
window, that diagram is displayed in the foreground. 


Performance Analyzer - Window Manager 


File View Options Project Help 


- □ 


?n E:\OVIEW\OVIEW.EXE 

E:\OVIEW\OVIEW.TRC 


OVIEW.TRC - Dynamic Call Graph 


Create Trace... Analyze Trace... 


Figure 36. Updated Window Manager window 
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2. You can change the size of the graphical representation of the functions by 
turning scaling off. To do this, open the Options pulldown menu and click on 

Scale node sizes. 

The nodes in the graph become the same size. 


OVIEW.TRC - Dynamic Call Graph 


Trace file View Options Project Help 


Trace description: 
Filters: none 

Selected obj ect: main 



Figure 37. Dynamic Call Graph with scaling off 
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3. Move the mouse pointer to the slider bar on the left side of the window. Press 
and hold mouse button 1, drag the bar half-way down the slider, and release 
mouse button 1. 

The graph zooms in and you can see the description of the nodes. 



Figure 38. Zoom in using the slider bar 
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4. Use the scroll bar on the right side of the window and scroll down until the 
entire graph displays in the window. Click on the TString::showString() node. 



OVIEW.TRC - Dynamic Call Graph 


Trace file View Options Project Help 


Trace description: 

Filters: none 

Selected object: TString::showstring0 


ostream::opcrator< 


Figure 39. Status Area updated 


The Status area, below the menu bar, is updated with the description of the 

Selected object, (TString::showString()). 

If the Status area is not shown, select Status area on the Options pulldown 
menu, click on the Select all pushbutton in the Status Area window, and then 
click on OK. 

If scaling is turned on, you can use this method to identify the node in the graph. 


46 


Welcome to VisualAge C++ 




Getting Started 


5. If you click on the arc between main and TString::showString(), the status area 
is updated again to show that main called TString ... . 



Figure 40. Status Area updated 


If scaling is turned on, you can use this method to identify the source and 
destination of the call. 

6. Double-click mouse button 1 on main. 

A Function Information window opens. It shows data for Execution time. 
Time on stack, and Number of calls. 


Function Information 


main I 

I OVIEW E:\OVIEW\OVIEW.EXE 

g 







Execution time : 4.979 s 92% 

Time on stack : 5.416 s 100% 

Number of calls : 1 


Who calls me 


Whom do I call 


Cancel 


Help 


Figure 41. Function Information window 
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7. Position the Function Information window so you can see the graph, then click 
on the Who calls me pushbutton. 



| OVIEW.TRC - Dynamic Call Graph 

_| " □ 

Trace file View Options Project 

Help 


|Trace description: 

Filters: Who calls me 

Selected obj ect :_ main_ 




w 

c 

3 

■ 




main 



Function Information 


main 

1 OVIEW E:\OVIEW\OVIEW.EXE 







Execution time : 4.979 s 92% 

Time on stack : 5.416 s 100% 

Number of calls : 1 



Who calls me 

Whom do 1 call 

Cancel 

Help 






Figure 42. Graph shows the result of Who Calls Me 

Since main is not called, it is the only node shown in the graph. 
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Now click on the Whom do I call pushbutton, and the graph is updated to show 
who main calls. 


|4| OVIEW.TRC - Dynamic Call Graph 

° □ 

Trace file View Options Project Help 

Trace description: 


Filters: Whom do I call 


[Selected object:_main_ 




Execution time : 4.979 s 92% 

Time on stack : 5.416 s 100% 

Number of calls : 1 



Figure 43. Graph shows the result of Whom Do I Call 

8. Click on the Cancel pushbutton to close the Function Information window. 
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9. Double-click on the arc between main and TString::showString(). 

This opens a Who Calls Whom window and shows that main called 
TS tring:: showS tring(). 


Who Calls Whom 


main 

1 OVIEW E:\0VIEW\0VIE 

Wl 

4 




> 


called 


TString::showString() I 

IMP E:\OVIEW\OVIEW.EXR 



ELI .I i>2 

> 

1 out of 1 times. 

Find Callerl Find Callee 

Cancel Help 


Figure 44. Who Calls Whom window 
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10. Position the Who Calls Whom window so you can view the graph. Click on the 
Find Caller pushbutton. 

The node for main is highlighted within a green box to show that main is the 
caller. 


|J^| OVIEW.TRC - Dynamic Call Graph 

- □ 

Trace file View Options Project Help 

Trace description: 


Filters: Whom do I call 


Selected object:_main_ 

-- 



| TString::showString() | IMP E:\OVIEW\OVIEW.EXE j| 


II I 

; aaK»»a8saiMS«ai i ata«t^^ 

1 out of 1 times. 

Find Cafieri Find Callee | j Cancel Help 


Figure 45. Find Caller result highlighted in the graph 
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11. Click on the Find Callee pushbutton. 

The node for TString::showString() is highlighted within a green box to show 
that TString::showString() is the callee. 


|fr| OVIEW.TRC - Dynamic Call Graph « □ 

Trace file View Options Project Help 


Trace description: 

Filters: Whom do I call 

[Selected object: TString::showString() 



Figure 46. Find Callee result highlighted in the graph 

12. Click on the Cancel pushbutton to close the Who Calls Whom window. 

13. Select Restore nodes in the View pulldown menu. 

The full graph is redrawn. 

When you work with a more detailed graphical representation of trace data, the 
ability to scale, zoom in and out, display function information, and display caller 
and callee information, gives you an effective means of analyzing the call 
structure of your application. 

The next section describes the Call Nesting diagram. Leave the Dynamic Call 
Graph window open and re-position it to partially overlay the Window Manager 
window. 
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Call Nesting Diagram 

In this section you open the Call Nesting diagram from the Dynamic Call Graph 
that you opened in the previous section. 

1. Select the Open as item in the Trace file pulldown menu of the Dynamic Call 
Graph window. Now select Call Nesting to open another diagram. 

A Call Nesting window opens and the Window Manager window is updated to 
show that both Call Nesting and Dynamic Call Graph windows are open. 


IH OVIEW.TRC - Call Nesting 


Trace file Edit View Options Project Help 

Trace description: 

Filters: _none 

~\ main 

— I TString::setString(char«) 

_ Istrcpy 


TString::showString() 

~I ostream::operator<<(ostream&(*)(ostream&)) 


ostream::operator<<(ostream&(*)(ostream&)) 


J > 


Figure 47. Call Nesting diagram 


Position the windows so that the Call Nesting window partially overlays the 

Window Manager window and the Dynamic Call Graph window. 

The Call Nesting window shows the trace file as a series of function calls and 
returns. A call is shown as a step to the right, and a return as a line to the left. 
You can clearly see the flow of control. 
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2. Click mouse button 1 on the strcpy call to highlight it, then select Call stack on 
the Options pulldown menu. 


Trace description: 

Filters:_none_ 


main 

TS 

>tring::setString(c 

strcpy 


OVIEW.TRC - Call Nesting 


° □ 


Trace file Edit View Options Project Help 

Call stack... ^ 

Correlation... - 

Font- 

Thread layout- 

Status area... 

Tool bar + 


TString::showStrinc settings ■+ 

ostream::operator<<(ostream&(*)(6stream&)) 


ostream::operator<<(ostream&( K )(ostream&)) 


Figure 48. Call Nesting diagram with Options pulldown menu 


A Call Stack window opens showing the Functions in the call stack (on the 
left), and the Object File and the Executable for each function (on the right). 


Call Stack 


Call Stack for thread 1: 


Function 

Object File Executable 

strcpy. 

IMP E:\OVIEW\ 

U 

TString::setString(char*) 

main 

IMP E:\OVIEW\ 

OVIEW E:\OVIEW\ 



1 1 1 _>J 



Ok 


Help 


Figure 49. Call Stack window 

3. Click on OK to close the Call Stack window. 
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The Call Nesting diagram is re-used in the next section. The next section describes 
the Time Line diagram. Leave the Call Nesting window open and re-position it to 
partially overlay the Dynamic Call Graph. 

Time Line Diagram 

In this section you open the Time Line diagram from the Call Nesting diagram that 
you opened in the previous section. 

Select the Open as item in the Trace file pulldown menu of the hp2.Call Nesting 
diagram. Now select Time Line to open another diagram. 

1. Leave the Call Nesting diagram open and select the Open as item in the Trace 
file pulldown menu. Now select Time Line to open another diagram. 

A Time Line window opens and the Window Manager window is updated to 
show the diagrams that are open. 


Trace description: 
Time slice: 
Selected region: 

— 0 ms 


OVIEW.TRC - Time Line 


Trace file Edit View Options Project Help 


□ 


863 us 
Start time = 


863.000 us End time = 863.000 us Elapsed time = 0.000 J 


| 100 ms 


TString::showString() 


‘2O0 ms 


ostream::operator<<(ostream&(*)(ostrean 


Figure 50. Time Line window 


The Time Line diagram displays the sequence of nested calls and returns. Time 
stamps determine the exact placement of an event along the time dimension as a 
vertical axis. This shows the chronological relationship of events. 


Chapter 2. Getting Started with VisualAge C++ 55 




Getting Started 


2. There is a narrow horizontal line across the diagram at the 0 ms position. Move 
the mouse pointer to this line, press and hold mouse button 1, and drag the line 
just past ostream::operator and release mouse button 1. 


[Trace description: 
'Time slice: 
Selected region: 

— G ms 


OVIEW.TRC - Time Line 


Trace file Edit View Options Project Help 


□ 


863 us 
Start time 


863.090 us End time = 143.298 ms Elapsed time = 142. 43* 


— 10Q ms 


TString::showString() 


— 200 ms 


ostream::operator<<(ostream&(*)(ostrean 


Figure 51. Time Line window with a time slice highlighted 


As you do this, the Start time. End time, and Elapsed time are updated in the 
Status area. 

If the Status area is not shown, select Status area on the Options pulldown 
menu, click on the Select all pushbutton in the Status Area window, and then 
click on OK. 

3. You can correlate the Time Line diagram to the Call Nesting diagram, (the 
Performance Analyzer provides correlation for the three time-scaled diagrams: 

Call Nesting, Execution Density, and Time Line.) 

Open the Options pulldown menu and select Correlation. 

A Correlation Window opens and shows that you can correlate the Time Line 
diagram with the Call Nesting diagram that is open. 
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4. Click on OVIEW.TRC - Call Nesting to select it, and click on OK. 


Correlation 


Windows to Correlate: 


lOVIEW.TRC - Call Nestim 


QK It 


Select all 


Deselect all 


Cancel 


Help 


Figure 52. Correlation window 


The Call Nesting diagram is displayed in the foreground and shows a shaded 
area correlated with the shaded area in the Time Line diagram. This gives you 
the capability to compare views when you analyze your application. 


IH OVIEW.TRC - Call Nesting 


Trace file Edit View Options Project Help 

Trace description: 

F ilters: none 

~~1 main 

— I TString::setString(char*) 

_ Istrcpy 


TString::showString() 

~I ostream::operator<<(ostream&(*)(ostream&)) 


ostream::operator<<(ostream&(«)(ostream&)) 


> 


Figure 53. Correlation of a Time Line diagram to a Call Nesting diagram 

For more information about correlating diagrams, see the Performance Analyzer 
online help available through the Help pulldown menu. 

The next section describes the Execution Density diagram. Leave the Call Nesting 
window open and re-position it to partially overlay the Time Line diagram. 
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Execution Density Diagram 

In this section you open the Execution Density diagram from the Call Nesting 
diagram that you brought to the foreground in the previous section. 

1. Select the Open as item in the Trace file pulldown menu of the Call Nesting 
diagram. Now select Execution Density to open another diagram. 

An Execution Density window opens, and the Window Manager window is 
updated to show the windows open in the Performance Analyzer session. 




OVIEW.TRC - Execution Density 


° □ 


main 

1 


Trace file Edit View Options Project Help 

Trace description: 

Time slice: 24.861 ms 

Selected region: Start time = Q. GGG us End time = 0. GGG us Elapsed time = G.GGG us 

Filters: none 

Selected object: 

— Os 
- 1 s 
I 2 s 
-3 s 
A s 
I—5 s 
-6 s 
I—7 s 


Figure 54. Execution Density window 

The Selected object in the status area is main. (If the Status area is not shown, 
select Status area on the Options pulldown menu, click on the Select all 
pushbutton in the Status Area window, and then click on OK.) 

A column indicator arrow in the diagram shows the column for main. (The 
left-most column.) 

The Execution Density diagram shows trends of program execution. It displays 
the trace data chronologically, from top to bottom, as thin horizontal lines of 
various colors in different columns. 
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2. Position the mouse pointer at the column to the right of the column indicator 
arrow and click mouse button 1. 



Figure 55. Results of re-positioned column indicator 

This re-positions the arrow and the Selected object for that column is identified 
in the Status area. As you continue to re-position the column indicator arrow 
from left to right, you see the identification of the selected object in the Status 
area. 


Chapter 2. Getting Started with VisualAge C++ 59 



Getting Started 


3. Click mouse button 1 on the 1 s line, and the horizontal time line is positioned at 
that point. Times in the Status area are updated. 



Figure 56. Results of re-positioned time line 
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4. Position the mouse pointer on the horizontal line, press and hold mouse button 1, 
drag the line down to the 2 s range, and release mouse button 1. 


Trace description: 

iTime slice: 24.861 ms 

JSelected region: Start time = 944.728 ms End time = 2.Q14 s Elapsed time = 1.869 s 

Filters: none 


OVIEW.TRC - Execution Density 


Trace file Edit View Options Project Help 


□ 


[Selected object: 

' 0 s 

— 1 s 

“ 2s * 

— 3 s 

— A s 
-5 s 

— 6 s 

— 7 s 


TSt ^rinq ::setSt rinqtchar* ) 


1 


Figure 57. Highlighted time slice and updated status area 


As you drag the line down, the End time and the Elapsed Time fields are 
updated in the status area. 

You can also correlate this diagram with the Call Nesting and the Time Line 
diagrams. For more information about correlating diagrams, see the Performance 
Analyzer online help available through the Help pulldown menu. 

The next section describes the Statistics diagram. Leave the Execution Density 
diagram open and re-position it to partially overlay the other Performance Analyzer 
diagrams. 
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Statistics Diagram 

In this section you open the Statistics diagram from the Execution Density diagram 
that you opened in the previous section. 

1. Select the Open as cascade menu in the Trace file pulldown menu of the 
Execution Density window. Now select Statistics to open another window. 

A Statistics window opens and the Window Manager window is updated to 
show that all of the Performance Analyzer diagrams are open. 


OVIEW.TRC - Statistics 


Trace file View Options Project Help 


° □ 


Summary 


ixecutable name: E:\OVIEW\OVIEW.EXE 


Execution date: 05/O8/95 
Execution time: 11:37:38 AM 


Function 


Details 

% Of Execution % On Stack Number of C;| 


ostream::operator< 

TString::showStrim 

ostream::operator< 

strcpy 

TString::setString(i 


Figure 58. Statistics window 
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Figure 59. Updated Window Manager window 

The Statistics diagram gives you a textual report of execution time by function 
or executable. Use this information to find hot spots in the overall program 
execution. 

The diagram has a Statistics Summary pane, and a Details pane. 

In the Details pane, use the horizontal scroll bar on the bottom right to scroll 
through the various detail categories. The times shown are in milliseconds. 

The Statistics diagram gives you a comprehensive statistical summary of the 
performance of your application. 

2. Close the Performance Analyzer by pressing F3 in any of the Performance 
Analyzer windows. 

The series of diagrams that you reviewed gives you an insight into the capabilities of 
the Performance Analyzer. For more detailed information about the Performance 
Analyzer see the Performance Execution Trace Analyzer section in the User's Guide. 
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You can use the Help pulldown menu in any Performance Analyzer window to 
access: 

• General help, to review the functions available in the various diagrams 

• How do I? help, for information about interpreting the diagrams. 

For additional information about the concepts and functions referenced within this 
Use the Performance Analyzer section, see: 

• “Window Manager Window” on page 91 

• “Trace Generation Window” on page 92 

• “Analyze Trace Window” on page 93 

• “Call Nesting Diagram” on page 53 

• “Dynamic Call Graph” on page 95 

• “Execution Density Diagram” on page 58 

• “Statistics” on page 97 

• “Time Line” on page 98. 


Getting Started Summary 

You have now completed Getting Started with VisualAge C++. 

You used the VisualAge C++ product to open a WorkFrame project's Icon View. 
The integrated development environment allowed you to use the Editor, Browser, 
Debugger, and Performance Analyzer through actions defined for the project. 
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Creating WorkFrame Projects 


This chapter describes two ways to create WorkFrame projects. 

You can use Project Smarts to create a project that has a set of skeleton files and 
project actions defined for you. 

You can drag the VisualAge C++ Project Template from the VisualAge C++ folder 
to the desktop to create a project with VisualAge C++ default settings. 


Project Smarts 

Project Smarts creates a project folder for you when you select an application from 
the Project Smarts catalog. 

1. Open the Project Smarts folder contained in the VisualAge folder. 


© Copyright IBM Corp. 1995 
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Project Smarts - Catalog View 


Use Project Smarts to create a project to 
suit your needs. Select one of the 
following customizable projects and click 
on "Create". 


□ 


Available projects: 


C++ Dynamic Link Library 
Data Access Application 
Direct-to-SOM Application 
IPF Context-Sensitive Help 


Description of the selected project: 

A template for building a basic C DLL. 
You can choose to link statically or 
dynamically to the single- or 
multi-threaded C Set ++ runtime library. 


Create 


Cancel 


Help 


The name of the project to be created. 


Figure 60. Project Smarts catalog 


As you click on each application name in the Project list, a description of the 
application appears in the Description field. 

2. To create a Presentation Manager Application project, select Presentation 

Manager Application in the Available projects list box of the catalog, and then 
click on the Create pushbutton. 

A Target Information window opens that defines the name and location of the 
new project. Leave the information as is and click on OK. 
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A Variable Settings window opens that lets you customize some of the settings 
for your project. 


Project Smarts - Variable Settings 


□ 


Project Smarts substitutes the following symbolic 
variables into the source files it creates for your 
project. You can change their settings to customize 
your project. 


Variable: 
File name 


Runtime librar 


Linking 

Custom _lnit_T erm 
Prolog_ 


Variable description: 

Specify the runtime 
libraries you want to use: 

1 for single-threaded 

2 for multi-threaded 


Variable setting: 

1 


OK 


Reset 


Cancel 


Help 


The symbolic variable name used in file substitution. 


Figure 61. Project Smarts Variable Settings window 

3. Leave the variable settings as is and click on OK. 

A Project Smarts - Console window opens to show you the progress of the 
project being created. 

A message dialog indicates that the project has been created on your desktop. 

A page in the Smarts settings view allows you to bypass the console and 
variable settings dialogs. These are displayed by default. 

4. Close the Project Smarts window, locate the Presentation Manager 
Application project folder on the desktop and open it. 


The project contains a number of files coded for a PM application. You are now 
ready to begin developing the specifics of your application by using those 
skeleton files. 
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5. See the Project Smarts section in the User's Guide for a more detailed 
description of Project Smarts. 

For additional information about the concepts and functions referenced within this 
Project Smarts section, see: 

• “Variable Settings” on page 99. 


VisualAge C++ Project Template 

The following steps show you how to create a project by dragging the 
VisualAge C++ Projects Template from the VisualAge C++ folder. 

1. Locate the VisualAge C++ Project Template in the VisualAge C++ folder, and 
drag it to your desktop. 


VisualAge C++ 
Project Template 


BW| VisualAge C++ - Icon View 


VisualAge C++ 
Tools 


Samples 


a. 


VisualAge C++ 
Information 

How Do I...? 


|~^^| Project Smarts 


README 


Window 


□ 


Welcome to 
VisualAge C++ 


Figure 62. A VisualAge C++ Project Template dragged to the desktop 


The template icon changes to a project folder icon. 
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2. To change the name of the project to Oview: 

• Place the mouse pointer on the name 

• Press and hold the Alt key and click mouse button 1 



VisualAge C++ 
ProjectTemplate 


Figure 63. The project name field highlighted 

• Use the Backspace key or the Delete key to erase the name in the 
highlighted field 

• Type Oview in the highlighted field 



Oview 


Figure 64. Oview project name added 

• Move the mouse pointer away from the name field and click mouse button 1 
to complete the name change. 



y s 


Oview 


Figure 65. Project renamed to Oview 

3. By using the VisualAge C++ Project Template to create the Oview project, the 
new project inherits all of the actions available to VisualAge C++. 

Now you need to tailor some of these actions to complete the minimum 
requirements for setting up the project. You will use the same files that were 
used in Getting Started with VisualAge C++. 

You need to specify: 

• The target of your project (such as an EXE or a DLL) 

• A make file name 

• The working directory 
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• The Build actions that apply to the files in the project. 

The next section takes you through the process of changing the project's settings. In 
the section after that, you change the Build action settings. 

Oview Project Settings 

In this part you change the project settings to specify the project target, the make file 
name, and the working directory. 

1. Click mouse button 2 on the Oview project folder to open a pop-up menu. Click 
on the arrow beside Open and select Settings on the cascade menu to open the 
Oview settings notebook. (That is, select Open —* Settings.) 

The notebook opens at the Target page. 

2. To specify the target and make file name: 

• On the Target page of the Oview settings notebook, type oview.exe to 
replace target.exe 

• Type oview.mak to replace makefile 



. . L ' 

=j3 Name oview.exe 

target 

i-1 1 

Run options 

% _ 

= ocation 

Monitor 


Inheritance 

=3 Makefile oview.mak 

* 

View 

Sort 


Menu 

1 

File 


Window 

| 

General 

I __ 

=p* | Undo | | Default | Help | 



«• [+ 


Figure 66. Target page updated 
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3. To specify the location of your source files and the working directory: 

• Click on the Location tab of the notebook 

• In the Source directories for project files box, replace the existing entry 
with the following: 

d :\ibmcpp\samples\welcome 

where d: represents the drive where you installed the samples directory. For 
example, if you installed the samples directory on your e: drive, you would 
enter e:\ibmcpp\samples\welcome. By doing this, you associate the files in 
the welcome subdirectory with the Oview project. 

• In the Working directory field, click on the down arrow of the list box and 
the directory specified as the source directory automatically becomes the 
working directory. 


i 


1 


i 

t! 


$ 


I 


Oview - Settings 


Location - OS/2 Files 

Source directories for project files: 
e:\ibmcpp\samples\welcome 


:: □ 


Working directory: 


e:\ibmcpp\samples\welcom 


e:\ibmcpp\samples\welcome 


Target 

Location 



Figure 67. Target page updated 


You can specify more than one source directory in the Source directories box. 

If you do, you can then select which directory you want as the working directory 
from the drop-down list box under Working directories. 
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4. Close the Oview notebook by double-clicking on the icon in the top left comer of 
the window. 

In the next section you change the Build action settings. 

Build Action Settings 

In this part you change the Build action settings for compiling and linking the source 
files. 

1. To specify the Build actions for the project, click mouse button 2 on the project 
folder to open the pop-up menu, and select Open —» Tools setup. 

The Actions view of the Tools setup window opens. 



Figure 68. Tools setup window 
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2. Click on the + icon beside Build to expand the Build tree, then click mouse 
button 2 on Build normal to open a pop-up menu. Select Project options to 
open a WorkFrame Build Options window. 



Figure 69. Opening the Build Normal Project options 
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3. Since the source code is written in C++, and since the target of the Build action 
is an exe file, you will want to perform a compile and link operation. Select the 
following in the Actions list box: 

• Compile::C++ Compiler 

• Link::Linker. (You may have to scroll to find the Link item.) 

The Actions list box contains a list of file-scoped actions eligible for 
participation in a build. These actions have both source and target types 
specified in their settings. The Build utility attempts to formulate the build rules 
for your project by examining the source files and the source and target types of 
the file-scoped actions in the project. 


WorkFrame Build Options 


□ 


Actions used to build the project. 


Actions 


Bind::Resource Bind 


Compile::C++ Compiler 


Compile::IPF Compiler 
Compile::Message Compiler 
Compile::Resource Compiler 
Compile::SOM Compiler 
Compile::SQL Precompile 




Reset 


Default 


Help 


OK 


Reset 


Default 


MakeMake 

Make 

* 





Project 


Display 


Cancel 


Help 


Figure 70. Selecting the C++ Compile and Link actions 

4. Select the OK pushbutton to set the actions and to close the WorkFrame Build 
Options window. 

5. Close the Oview Actions window by double-clicking on the icon in the top left 
corner of the window. 

You have now completed the setup of the Build action. It will perform a 
compile and link operation on oview.cpp and imp.cpp. 
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6. Open the Oview project icon view by double-clicking mouse button 1 on the 
project folder. The parts container should have oview.cpp, imp.cpp, and 
teststrg.hpp in it. There may also be other files represented in the parts 
container as a result of the steps you performed in the Getting Started with 
VisualAge C++ section. (If the project Monitor is not shown, either click on 
the monitor icon in the Monitor toolbar, or select Show on the Monitor 
pulldown menu.) 


K*] Oview 


Project Selected Monitor View Options Help 


|»«a D 




B OVIEW.TRC 
S OVIEW.EXE 
OVIEW.OBJ 
OVIEW.PDB 


[5l IMP.OBJ 
[^1 IMP.PDB 
|K OVIEW.CPP 
B TESTSTRG.HPP 


OVIEW.MAK 
|g ! IMP.CPP 


□ 


man sum m 


Figure 71. Oview Project - Icon View 


To verify that the Build action performs the compile and link operation to create 
an exe file and obj files, delete all of the files except oview.cpp, imp.cpp, and 
teststrg.hpp. (Select Delete on the pop-up menus of the files to be deleted.) 

7. Start the Build action by selecting Build from the Project pulldown menu. 

The build runs successfully and the exe and obj files are created. 
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8. Since the Oview project inherited the actions available to VisualAge C++, open 
the C++ Compiler options notebook to see the compile options that were 
inherited. To do this: 

• open the pulldown menu of the Options item in the project menu bar 

• select Compile. 

You can also open the C++ Compiler notebook by: 

• Selecting Tools setup from the View pulldown menu 

• expand the Compile action tree (click on the + icon), in the Tools setup 
window 

• Click mouse button 2 on C++ Compiler to open the pop-up menu 

• Select File options. 

9. As you page through the compiler options notebook, you see that: 

• The Perform compile only radio button and the EXE target radio button are 
selected on the Processor page 

• The None radio button for Browser info, and the Object check box are 
selected for Produce file options on page 1 of the File section 

• The None radio button in the Debugging information field is selected on 
page 2 of the Debugging section 

The description of Build Smarts in the Getting Started with 
VisualAge C++ section, indicates that Build Smarts enables debugging by 
default. This means that even though debugging was not specified in the 
compiler options here. Build Smarts increments the options to include 
debugging. 

See “Build Smarts” on page 82 for a description of the Build Smarts 
operation. 

• The Off optimization radio button is selected on page 2 of the Object 
section 

• And, the Enable performance analyzer radio button is not selected on page 
2 of the Object section. 

10. Close the C++ Compiler options notebook by double-clicking on the icon in the 
top left corner of the window. 

11. If you review of the Linker options notebook, you will notice that the Linker 
options coincide with those of the C++ compiler. 

12. Close the Oview Icon View by double-clicking on the icon in the top left corner 
of the window. If you wish to delete the Oview project folder, click mouse 
button 2 on the folder, select Delete and select the Delete pushbutton in the 
Delete objects window. 
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For additional information about the concepts and functions referenced within this 
VisualAge C++ Project Template section, see: 

• “Inheriting a Tools Setup” on page 100 

• “Tools Setup Window” on page 101 

• “Build Smarts” on page 82. 


Creating WorkFrame Projects Summary 

You have now completed Creating WorkFrame Projects. 

You created projects by using: 

• Project Smarts 

• VisualAge C++ Project Template. 

You also set project-scoped and file-scoped actions relating to a project and to the 
objects associated with the project. 
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Concepts and Functions 



This chapter describes in more detail some of the concepts and functions that are 
referenced within Chapter 2, “Getting Started with VisualAge C++” on page 15, and 
Chapter 3, “Creating WorkFrame Projects” on page 65. The sequence of these 
concepts and functions is based on the order in which they occurred in those chapters. 


A WorkFrame Project 

A project represents the complete set of data and actions that you need to build a 
single target, such as a dynamic link library (DLL) or executable file (EXE). A 
project consists of a set of project parts and a tools setup. 

Project parts are the data objects that make up the project. Project parts may be 
source files, transient objects (such as a target or intermediate file that has been 
created), and even other projects. 

Project parts are conceptually contained in the project; they are not physically stored 
in the project. The project only stores the information necessary to access the parts. 

A target is a specially designated project part. It is created as the result of a build 
action invoked on the project. 

A project's Tools setup defines the actions, environment variables, and types that are 
available to the project. 

• Examples of actions are Compile, Link, Make, and Build. 

• Types provide a way of grouping and filtering project parts so that you can refer 
to them with a single name. Examples of types are C++ source, C source, and 
executables. 

• Environment variables are system environment variables, such as PATH, and any 
environment variables that are defined using the OS/2 SET command. 

For more information about projects and WorkFrame refer to the WorkFrame section 
in the User's Guide. 
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Project Icon View 

The prominent features of a project's Icon View are: 

• The Menu bar 

• The Project tool bar, which includes a Parts filter control with a drop-down list 
box 

• The project Parts container 

• The project Monitor 

• The Monitor toolbar. 
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Figure 72. A Project Icon View window 

Each of these is described below. 

The Menu Bar 

The project menu bar contains menu items: 

• to launch actions against the whole project or against selected files 

• control the project monitor 

• set options for common actions (like compile and link) 

• access help, the project settings pages and the tools setup view (where details of 
tool configuration are specified). 
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The Project Toolbar 

The project toolbar contains buttons for launching frequently-used, project-scoped 
actions like Build, Debug, and Run. Each button represents a single project-scoped 
action. You can customize the actions that appear on the toolbar by setting a control 
in an action's Settings notebook. The toolbar also contains the filter drop-down box, 
and buttons to access Build Smarts dialog, the Tools setup view, and the How do I? 
help. 

The Parts Filter 

The parts filter is an entry field on the project tool bar where you can enter a file 
mask or type name to filter the view of project parts. Only the parts that match the 
specified mask or type are displayed in the parts container. You can also use the 
drop-down list box to select from predefined types that are available to the project. 

The Parts Container 

The parts container is the area where the project parts are displayed. Project parts are 
almost always files, although they can be Workplace Shell objects, and other kinds of 
objects as well. The physical location or files or parts is specified on the Location 
page of the project's Settings notebook. The same information can be displayed in a 
Details view and a Tree view (similar to other Workplace shell containers). 

Project parts are displayed as icons in the project's Icon view container. You can 
control the layout and size of the icons from the View page of the project's Settings 
notebook. 

The Project Monitor 

The Monitor window displays the output from actions like Compile and Link. By 
default, it is hidden when you open a project but appears when a monitored action is 
started. 

Monitor behaviour can be tailored on the Monitor settings page. 

The Monitor Toolbar 

The Monitor toolbar contains buttons for controlling the project Monitor. An 
information line on the tool bar shows the name of the currently running action. 
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Project-Scoped Actions 

Project-scoped actions apply to a project as a whole, rather than to any selected set of 
project parts. These actions can be passed project information, such as the name of 
the project make file or target. Examples of project-scoped actions are Make, Build, 
Run, and Debug. The first two actions are invoked on the projects's make file, and 
the last two on the project's target. Although make files and target files are also 
project parts, they have a special designation, that is, their names are explicitly 
recognized by the project. 

Project-scoped actions can be invoked from the Project item on the menu bar, or 
from the project's pop-up menu. To open the project's pop-up menu, point to the 
background area in the project container and press mouse button 2. 

Project-scoped actions cannot be included in a make file. 


File-Scoped Actions 

File-scoped actions apply to specific project parts, and can only be invoked from 
those parts. To run a file-scoped action, you must select one or more project parts 
and then invoke the action on the selected parts. For example, the Visual Age C++ 
Compile action applies to parts that are of type C/C++ Source. This means that you 
can invoke the Visual Age C++ compile action by pointing to a .CPP file and 
selecting Compile —» VisualAge C++ from its pop-up menu. 

File-scoped actions can be invoked from the pop-up menus of the objects contained in 
the project, or from the Selected item on the menu bar. 


Build Smarts 

Each setting in the Build Smarts window can affect one or more VisualAge C++ 
actions. For instance, the Debugger check box affects the VisualAge C++ Compiler 
and Linker options. Selecting the Debugger check box effectively adds the /Ti 
option to the VisualAge C++ Compiler command line, and /DE to the 
VisualAge C++ Linker command line, when you initiate a build involving those 
actions. 
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21 Enable Build Smarts to add support for the following VisualAge C++ features: 

2! Debugger 

□ Browser 

□ Performance Analyzer 

□ Optimizer 

21 Generate a make file 
21 Build any subprojects first 

User macro sets 


Define Remove 



Figure 73. Build Smarts window 

The Build Smarts settings do not change the options already set for the individual 
actions in their options dialogs. The Tools setup settings are simply added to what is 
already set for the involved actions. When there are conflicts, the Build Smarts 
settings override those already set for the individual actions. 

Two important build options are also included here: Generate a make file and Build 
any subprojects first. Select the first option to generate a new make file as part of 
running the build. Select the second option to build any child projects before 
building the current project so that all the dependencies are up to date. 

At any time, you can disable the Build Smarts options by deselecting the Enable 
Build Smarts features check box if you only want to use the options set for the 
individual VisualAge C++ actions. 
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Program Profile 

If you enable the Use program profile checkbox in the Program Startup window, 
you can restore debugger windows and breakpoints when debugging a program more 
than once. 


y| Program Startup _ 

Program D:\ipmd\CPPLINES.EXE s File List... 

Parameters 


□ Debug child process(es) 

Child name(s) | Child list... 

□ Debug program initialization 
§3 Use program profile 


OK 


Reset Default Cancel 


Help 


Figure 74. Program Startup window with Use program profile enabled 


Program profiles are stored separately for each program debugged. 

Note: Only information for executable files and preloaded DLL's relating to the 
primary thread is restored. 

The Program Profile warning dialog appears because the program profile checkbox is 
enabled and the program is being debugged again. You can indicate whether or not 
you want to use program profile from the last debugging session for the program. 


Debugger Control 

The Debugger Control window is displayed during the entire debugging session. 
This control window gives you access to debugging functions through the pulldown 
menus of the items in the menu bar. The functions include: 

• Opening source windows 

• Setting breakpoints 

• Opening monitor, call stack, registers, and storage windows 

• Selecting run choices for program execution 

• Controlling how debugger windows display 

• Displaying help information. 
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The Debugger Control window is divided into two panes. One pane shows the 
threads for the program you are debugging, and the other pane shows the components 
for the program you are debugging. 
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Figure 75. Debugger Control window 

The Threads box contains the threads and the state of the threads that have been 
started by your program. 

The following states are possible for the threads listed in the Threads box: 

Enabled and runnable 
Disabled and runnable 
Critical and runnable 
Suspended and runnable 
Enabled and blocked 
Disabled and blocked 
Critical and blocked 
Suspended and blocked. 

To display the state of a thread, select the plus icon to the left of the thread. To 
enable or disable the thread listed in the Threads pane, double-click on the word 
Enabled or Disabled, depending on the state of the thread. You can also toggle the 
Thread enabled choice from the Run menu. 

When a check mark symbol displays beside the Thread enabled choice, threads are 
enabled and the debugger allows the highlighted thread to execute. When the check 
mark symbol does not display, the threads are disabled and do not execute. 
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The Components box shows the executable files that are associated with the program 
you are debugging. To display a list of the object files contained within an 
executable file, select the plus icon to the left of the executable file name. To open a 
source window of an object file, double-click on the object file name. To display a 
list of functions for a specific object file, select the plus icon to the left of the object 
file name. To open a source window of a specific function, double-click on the 
function name. 

To display a list of object files contained within an executable file, select the plus 
icon to the left of the executable file name. To open a source window of an object, 
double-click on the object file name. 

To display a list of functions for a specific object file, select the plus icon to the left 
of the object file name. To open a source window of a specific function, double-click 
on the function name. 

You can display any object or function by double-clicking on the name in the 
Componentsbox or by highlighting the component name and selecting a view from 
the View menu in one of the source windows. 

You specify which components display in the Components list by selecting 
Options-*Window Settings—»Only components with debugging data. When this 
choice is enabled, only components compiled and linked with debugging data are 
listed. Otherwise, all components are listed. 


Debugger Source Windows 

A source window allows you to view the program you are debugging. You can look 
at your source in one of the following windows: 

• Source 

• Disassembly 

• Mixed. 

A source window is thread-specific. Executable lines initially display in blue and 
non-executable lines initially display in black. 
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The Source window displays the source code for the object that contains the main 
function to the program being debugged. If it is available, the Source window 
displays with the Control window when the debugging session starts. Otherwise, the 
Disassembly window displays. 
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Figure 76. Source window 
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The Disassembly window displays the assembler instructions for your program, 
without symbolic information. 
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Figure 77 . Disassembly window 

The Mixed window displays your program as follows: 

• Each line of source code is prefixed by its line number, as in the Source 
window. 

• Each disassembled line is prefixed by an address, as in the Disassembly window. 

• Source comment lines also display. 

• The lines of source code are treated as comments within the lines of disassembly 
code. You can only set breakpoints or run your program on lines of disassembly 
code. 

Note: The Mixed window cannot be opened if the source code is not available. 
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CPPLINES Thread 1 - Mixed 
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Figure 78. Mixed window 


Step Commands 

Step commands control the execution of the program. The execution of the line of 
code is reflected in all open views, and is performed in the thread specific to the 
view. 

The step commands are located in the title bar of the source windows and under the 
Run menu of the source windows. 

To single step your program, click mouse button 2. This executes the current line in 
the program. 
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Browser Overview Window 

You can view an overview of the graph using the Overview... item on either the 
View pulldown or a Graph window Background popup menu. When using the 
Overview, you have a miniature version of the graph window. 
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Figure 79. Overview window 


The grey shaded area indicates the current view of the Graph Area in the graph 
window. You can move this area around or resize it. Any changes you make to the 
size or position of this grey area is automatically reflected in the Graph window. 

To size the view of the graph, grab the sides of the grey box and resize the area 
being shown in the diagram window. The result is the same as if you had used the 
Slider on the left side of the Graph window. Use the four-way cross-arrow to move 
the grey area around. Press and hold mouse button 1 to move the grey area. The 
result is the same as if you had used the scroll bars around the Graph Area of the 
Graph window. 
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Window Manager Window 

The Performance Analyzer - Window Manager window is the Performance 
Analyzer's main control window and is always displayed while the Performance 
Analyzer is running. Once you have properly compiled and linked your program and 
started the Performance Analyzer, you can start most functions from this window, 
including creating and analyzing trace files. 


[H Performance Analyzer - Window Manager 


File View Options Project Help 


?n E:\OVIEW\OVIEW.EXE 

|^) Qj E:\OVIEW\OVIEW.TRC 

■ 

OVIEW.TRC - Dynamic Call Graph 
OVIEW.TRC - Call Nesting 
OVIEW.TRC - Time Line 
OVIEW.TRC - Execution Density 






_ ■ ■ 


OVIEW.TRC - Statistics 


□ □ 


Create Trace... Analyze Trace.. 


Figure 80. Window Manager window 


When you view a trace file, this window lists the file names of your executable, your 
trace file, and each open diagram. 
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Trace Generation Window 

The Trace Generation window lists the file names of the preloaded components in 
the program, and lets you control which parts or your program are traced. 


□ 


OVIEW.EXE - Trace Generation 


□ 


Application Edit View Options Project Help 

ITI1MMMMMBBI 


Trace 


Figure 81. Trace Generation window 

A component can be an executable file, a dynamic link library file, an object file, or a 
function. EXE and DLL files contain object files, and object files contain functions. 
Object files are compiler output files that are linked to comprise an executable. A 
function is defined by the Performance Analyzer as a callable section within the 
application. For the Performance Analyzer, procedures and functions are 
synonymous. 

To view or hide components, click on the plus/minus icons to expand and contract 
EXE, DLL, and object files. 

Note: For an executable or object file to be traceable, you must include debugging 
information by compiling and. linking the application with the proper debugging 
options. 
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Analyze Trace Window 

The Analyze Trace window lets you specify the name of the trace file that you want 
to analyze and the diagrams in which you want to display the trace data. 

The five diagrams are: Call Nesting, Dynamic Call Graph, Execution Density, 
Statistics, and Time Line. 


Analyze Trace 


Trace File Name: 
E:\OVIEW\OVIEW.TRC 


Find... 


Diagrams 

□ Call Nesting 

[V Dynamic Call Graph 

□ Execution Density 

□ Statistics 

□ Time Line 


OK t 


Cancel 


Help 


Figure 82. Analyze Trace window 

Note: You must have created a trace file before you can open a diagram. 

You can display the Analyze Trace window from the Performance Analyzer - 
Window Manager window by: 

• Clicking on the Analyze Trace pushbutton 

• Selecting the Analyze trace choice from the File menu 

• Clicking mouse button 2 on a trace file name or icon (if displayed in the 
window), and selecting the Analyze trace choice from the pop-up menu. 


Chapter 4. Concepts and Functions 93 




Call Nesting 

The Call Nesting diagram shows the flow of control and interactions among the 
various threads. Use this diagram to diagnose problems with critical sections, 
sequencing protocols, thread delays, and program deadlocks and crashes. 



i ° □ i 

Trace file Edit View Options Project Help 

Trace description: 


Filters: none 


1 - 

main 

p 


TString::setString(char*) 


strcpy 


TString::showString() 

~I ostream::operator<<(ostream&(*)(ostream&)) 


ostream::operator<<(ostream&(*)(ostream&)) 

I > 


Figure 83. Call Nesting window 


Each thread in the Call Nesting diagram has its own starting column of functions. A 
call is shown as a step to the right and a return as a line back to the left. The calls 
are labeled with the function name being called. 

Context switches between threads are shown by dashed horizontal lines. While the 
vertical lines do not show elapsed scaled times in this diagram, you can clearly see 
the flow of control and the interactions among the various threads. 
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Dynamic Call Graph 

The Dynamic Call Graph shows an overall view of the program and the flow of the 
program. You can easily see where the most time was spent. This diagram uses 
nodes and arcs to represent functions and calls. 



OVIEW.TRC - Dynamic Call Graph 


Trace file View Options Project Help 


ostream:: operator < < (o$tream&( x )(ostream&)) 


Trace description: 
Filters: none 

Selected obj ect: main 


k < (ostream8c( x )(ostreamu)) 


Figure 84. Dynamic Call Graph 

Colors and sizes of nodes and arcs depict the time spent in the node and the number 
of calls between nodes. 

A node represents a function and appears as a rectangle on the diagram. An arc, 
which is displayed as a line between a pair of nodes, represents a call from one 
function to another. 

In the Dynamic Call Graph diagram, you can double-click on any: 

• Node for the Function Information window to display additional information 

• Arc for the Who Calls Whom window to display additional information. Only 
calls made during the given execution of the program are displayed. 
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Execution Density 

The Execution Density diagram shows trends of program execution by displaying 
trace data from top to bottom as a thin horizontal line of various colors in different 
columns. 



Trace file 

Edit View 

Options Project Help 

Trace description: 



Time slice: 

2 A. 861 ms 


Selected region: 

Start time = 0 

.000 us End time = 0.000 us Elapsed time = 0.000 us 

Filters: 

none 


Selected object: 

main 



-0 S 

-1 S 

— 2 s 

— 3 s 

— A s 

— 5 s 

— 6 s 

— 7 s 



Figure 85. Execution Density window 


This diagram consists of columns that contain thin lines of various colors: 

• Each vertical column represents a function 

• The thickness of each line represents a unit of time called a time slice 

• The color of each line represents the percentage of program execution time spent 
in the given function for that time slice. Only selected threads are used in 
calculating this percentage. 

For instance, in the default setting, functions executing more than 50 percent of a 
given time slice have a red line drawn in the appropriate column at the vertical 
location corresponding to the time slice. 

Magnification is initially turned off, meaning the entire trace file is visible in the 
window. You can magnify or filter the diagram to vary the amount of detail 
displayed. 
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Statistics 

The Statistical Summary gives you a textual report of execution time by function or 
executable. Use this diagram to find hot spots in the overall execution of the 
application. Hot spots are areas within an application where a disproportionate 
amount of time was spent. Plus, this information helps to determine which functions 
caused those hot spots. 


OVIEW.TRC - Statistics 


Trace file View Options Project Help 

Summary 


Executable name: E:\OVIEW\OVIEW.EXE 


Execution date: 05/Q8/95 
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Function 
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% On Stack 
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6 
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0 
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0 
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Figure 86. Statistics window 

You can also use this diagram to determine which user functions to inline. 

The Statistical Summary diagram has two panes: Statistics Summary Pane and 
Statistics Details Pane. 

The Summary pane is in the top-most area. You can scroll the windows and 
window panes to view the summary information. The Details window is divided into 
two panes. The left pane displays the fully qualified name of the component that 
statistics have been gathered on. The right pane lists statistics for each function. 
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Time Line 

The Time Line diagram places the function calls and returns in a sequence along a 
time line. Time stamps determine the exact placement of an event along the time 
dimension on the vertical axis. (A time stamp is the actual time at which an event 
occurred when the application was being traced.) This provides a direct and natural 
presentation of the chronological relationships of events. 



3 

□ 

Trace file 

Edit View Options Project Help 


Trace description: 
Time slice: 

Selected region: 

863 us 

Start time = 863.QQQ us End time = 863.QOQ us Elapsed time = Q.Q0Q u 

— 0 ms 

- 1 -_ . . _ 



! —100 ms 


TString::showString() 


'200 ms 


ostream::operator<<(ostream&(*)(ostrean 


Figure 87. Time Line window 

The Time Line diagram is similar to the Call Nesting diagram, but the distance 
between successive events in the diagram are drawn in proportion to the actual time 
between events as recorded in the trace file. 

The names of functions are only drawn when the time spent in that function is large 
enough to allow the name to be drawn. This value is dependent upon the size of the 
font being used. For example, with the default font, the distance between the call to 
the function and the next event must be at least twenty scan lines. This is done to 
ensure that the function name will not be overwritten by another function name or 
overdrawn by a line representing a function call or thread switch. 

You can use this diagram to find where a deadlock occurred. Access violations, 
system exceptions, and other such program errors are recorded in the trace file as user 
events, as are any messages generated in the code by calls to the Performance 
Analyzer. These events are indicated by a black diamon in the diagram, and if there 
is sufficient space, the associated text will be drawn to the right of the events. 
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Variable Settings 

Use the Variable Settings window, to customize a Project Smarts generated project 
by setting values for certain substitution variables, such as the source-file prolog text, 
current date, and user name. As you select each variable name in the Variable list 
box, the Variable description list box is updated with a short description about the 
variable. Verify the defaults and set values of your own by editing the Variable 
setting field. When you have verified all the variable settings, select the OK push 
button to continue with the installation. 

The values that you set are substituted when the application is installed. They are 
also saved for the next time you install the same Project Smarts application. 


Project Smarts - Variable Settings 


□ 


Project Smarts substitutes the following symbolic 
variables into the source files it creates for your 
project. You can change their settings to customize 
your project. 


Variable: 


File_name 


|Runtime_Ubrary j 

Linking 

y 

Custom_lnit_Term 


Prolon 

V 


Variable description: 

Specify the runtime 
libraries you want to use: 

1 for single-threaded 

2 for multi-threaded 


Variable setting: 
1 



Reset 


Cancel 


Help 


The symbolic variable name used in file substitution. 


Figure 88. Project Smarts Variable Settings window 

When the installation is complete, the created project appears on your desktop or in 
the folder you specified. You are now ready to begin working on developing the 
specifics of your application. 

For more information about Variable Settings see the Project Smarts chapter in the 
User's Guide. 
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Inheriting a Tools Setup 

Projects can share actions, environment variables, and types by inheriting the Tools 
setup of one or more projects. A project inherits from a list of base projects 
specified in the Inheritance page of the project's Settings notebook. 



Figure 89. Project Settings - Inheritance page 

Any changes made to a project's Tools setup, such as adding, deleting and changing 
actions and their options, are reflected in the projects that inherit from it. Thus, you 
could organize your projects into a group of Presentation Manager projects that all 
inherit from a base Presentation Manager project, a group of SOM projects, and so 
on, so that any changes made to the base project are propagated down to related 
projects. 

A project that inherits its Tools setup from other projects may also have locally 
defined actions, types, and environment variables that complement the inherited ones. 

Another alternative to project inheritance is to copy one or more actions, types, and 
variables from one project to another using drag-and-drop, or by selecting Copy... 
from their pop-up menus. The copied objects would then be defined locally in the 
target project, rather than inherited. 

You cannot add an action that has the same name and class as another action in the 
project, even if the other action is inherited. 
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For more information about project inheritance and the Tools setup see the 
WorkFrame section of the User's Guide. 

Tools Setup Window 

A project's Tools setup consists of the list of actions that can be used to manipulate 
the project and its parts, and the types and environment variables that support these 
actions. 



Figure 90. Tools Setup window 

The Tools setup window has three views, one each for actions, types, and variables. 
You can switch between the views by selecting Actions, Variables, or Types from 
the View menu in the Tools setup window, or using the buttons on the toolbar. 


Chapter 4. Concepts and Functions 101 







From the Tools setup window, you can : 

• Set options for all the actions in your project. Action options are the parameters 
that are passed to the tool when its action is invoked. 

• Add, delete, and change actions, types, and environment variables. 

• Copy and move actions, and environment variables from one project to another. 

• Find the project where an action, variable, or type is inherited from. 

These functions are available from both pop-up menus and the menus on the menu 
bar. The Actions, Types, and Variables menus on the Tools setup menu bar have 
the same items as the pop-up menus on actions, types, and environment variable 
objects in the Tools setup window. The View menu contains menu items to 
configure the information area at the bottom of the Tools setup window, the toolbar, 
and the view that appears when you open the window. 

For more information on how to perform tasks related to actions, types, and 
environment variables, refer to the WorkFrame section in the User's Guide, and to the 
How do I? help in the Help menu. 
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